Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Layout::JSON(3)	      User Contributed Perl Documentation      Layout::JSON(3)

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

       version 0.56

       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

	   # Note: Appender option!
	   # log4perl.appender.Example.warp_message = 0

       See below for more configuration	options.

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

       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.

       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.

       Specify a prefix	string for the JSON. For example:

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


       If this is turned on, the prefix	is treated as a
       Log::Log4perl::Layout::PatternLayout string, and	will be	rendered as a
       pattern layout.

       For example:

	   log4perl.appender.Example.layout.prefix = %m{chomp} @cee:
	   log4perl.appender.Example.layout.format_prefix = 1

       Would log "Hello	World" as:

	   Hello World @cee:{ .. MDC as	JSON ... }

       See also	"prefix"

       Exclude the message from	the JSON (default: 0).	If you are logging the
       message in the prefix for example, you may want to omit the message
       from the	JSON layout.

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

	   log4perl.appender.Example.layout.include_mdc	= 1

       See also	"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.

       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.

       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

       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.

       Switch JSON encoding from ASCII to UTF-8.

   warp_message	= 0
       The "warp_message" appender option is used to specify the desired
       behavior	for handling log calls with multiple arguments.	 The default
       behaviour ("warp_message" not set>) is to concatenate all arguments
       using "join( $Log::Log4perl::JOIN_MSG_ARRAY_CHAR, @log_args )" and
       setting a JSON field "message" to this simple string.

       If, on the other	hand, "warp_message = 0" is applied, then for log
       calls with multiple arguments these are considered name/value pairs and
       rendered	to a hash-like JSON structure.	For log	calls with an odd
       number of arguments (3 or more),	the first argument is considered the
       "message" and the others	are again considered name/value	pairs.

       See "Appenders Expecting	Message	Chunks"	in Log::Log4perl::Appender for
       more info on the	configuration option.

   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;



       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.)

       Originally created and maintained through v0.002003 by Tim Bunce.
       Versions	0.50 and later maintained by Michael Schout <>

       The development version is on github at
       <https://> and may
       be cloned from

       Please report any bugs or feature requests on the bugtracker website

       When submitting a bug or	request, please	include	a test-file or a patch
       to an existing test-file	that illustrates the bug or desired feature.

       Michael Schout <>

       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.

perl v5.32.1			  2018-07-21		       Layout::JSON(3)


Want to link to this manual page? Use this URL:

home | help