NAME
    Log::Log4perl::Layout::JSON

VERSION
    version 0.002003

SYNOPSIS
    Example configuration:

        log4perl.appender.Example.layout = Log::Log4perl::Layout::JSON
        log4perl.appender.Example.layout.field.message = %m{chomp}
        log4perl.appender.Example.layout.field.category = %c
        log4perl.appender.Example.layout.field.class = %C
        log4perl.appender.Example.layout.field.file = %F{1}
        log4perl.appender.Example.layout.field.sub = %M{1}
        log4perl.appender.Example.layout.include_mdc = 1

    See below for more configuration options.

DESCRIPTION
    This class implements a "Log::Log4perl" layout format, similar to
    Log::Log4perl::Layout::PatternLayout except that the output is a JSON
    hash.

    The JSON hash is ASCII encoded, with no newlines or other whitespace,
    and is suitable for output, via Log::Log4perl appenders, to files and
    syslog etc.

    Contextual data in the Log::Log4perl::MDC hash will be included if
    "include_mdc" is true.

NAME
    Log::Log4perl::Layout::JSON - Layout a log message as a JSON hash,
    including MDC data

LAYOUT CONFIGURATION
  field
    Specify one or more fields to include in the JSON hash. The value is a
    string containing one of more Log::Log4perl::Layout::PatternLayout
    placeholders. For example:

        log4perl.appender.Example.layout.field.message = %m{chomp}
        log4perl.appender.Example.layout.field.category = %c
        log4perl.appender.Example.layout.field.where = %F{1}:%L

    If no fields are specified, the default is "message = %m{chomp}". It is
    recommended that "message" be the first field.

  prefix
    Specify a prefix string for the JSON. For example:

        log4perl.appender.Example.layout.prefix = @cee:

    See http://blog.gerhards.net/2012/03/cee-enhanced-syslog-defined.html

  include_mdc
    Include the data in the Log::Log4perl::MDC hash.

        log4perl.appender.Example.layout.include_mdc = 1

    See also "name_for_mdc".

  name_for_mdc
    Use this name as the key in the JSON hash for the contents of MDC data

        log4perl.appender.Example.layout.name_for_mdc = mdc

    If not set then MDC data is placed at top level of the hash.

    Where MDC field names match the names of fields defined by the Log4perl
    configuration then the MDC values take precedence. This is currently
    construde as a feature.

  canonical
    If true then use canonical order for hash keys when encoding the JSON.

        log4perl.appender.Example.layout.canonical = 1

    This is mainly intended for testing.

  max_json_length_kb
    Set the maximum JSON length in kilobytes. The default is 20KB.

        log4perl.appender.Example.layout.max_json_length_kb = 3.8

    This is useful where some downstream system has a limit on the maximum
    size of a message.

    For example, rsyslog has a "maxMessageSize" configuration parameter with
    a default of 4KB. Longer messages are simply truncated (which would
    corrupt the JSON). We use rsyslog with maxMessageSize set to 128KB.

    If the JSON is larger than the specified size (not including "prefix")
    then some action is performed to reduce the size of the JSON.

    Currently fields are simply removed until the JSON is within the size.
    The MDC field/fields are removed first and then the fields specified in
    the Log4perl config, in reverse order. A message is printed on "STDERR"
    for each field removed.

    In future this rather dumb logic will be replaced by something smarter.

  EXAMPLE USING Log::Log4perl::MDC
        local Log::Log4perl::MDC->get_context->{request} = {
            request_uri => $req->request_uri,
            query_parameters => $req->query_parameters
        };

        # ...

        for my $id (@list_of_ids) {

            local Log::Log4perl::MDC->get_context->{id} = $id;

            do_something_useful($id);

        }

    Using code like that shown above, any log messages produced by
    do_something_useful() will automatically include the 'contextual data',
    showing the request URI, the hash of decoded query parameters, and the
    current value of $id.

    If there's a $SIG{__WARN__} handler setup to log warnings via
    "Log::Log4perl" then any warnings from perl, such as uninitialized
    values, will also be logged with this context data included.

    The use of "local" ensures that contextual data doesn't stay in the MDC
    beyond the relevant scope. (For more complex cases you could use
    something like Scope::Guard or simply take care to delete old data.)

AUTHOR
    Tim Bunce <Tim.Bunce@pobox.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2014 by Tim Bunce.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.