Log4j – Log4j 2 Layouts - Apache Log4j 2

Layouts

An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be consuming the log event. In Log4j 1.x and Logback Layouts were expected to transform an event into a String. In Log4j 2 Layouts return a byte array. This allows the result of the Layout to be useful in many more types of Appenders. However, this means you need to configure most Layouts with a Charset to ensure the byte array contains correct values.

JSONLayout

Appends a series of JSON events as strings serialized as bytes. This layout requires Jackson jar files (see pom.xml for details).

Complete well-formed JSON vs. fragment JSON

If you configure complete="true", the appender outputs a well-formed JSON document. By default, with complete="false", you should include the output as an external file in a separate file to form a well-formed JSON document.

A well-formed JSON document follows this pattern:

[
  {
    "logger":"com.foo.Bar",
    "timestamp":"1376681196470",
    "level":"INFO",
    "thread":"main",
    "message":"Message flushed with immediate flush=true"
  },
  {
    "logger":"com.foo.Bar",
    "timestamp":"1376681196471",
    "level":"ERROR",
    "thread":"main",
    "message":"Message flushed with immediate flush=true",
    "throwable":"java.lang.IllegalArgumentException: badarg\\n\\tat org.apache.logging.log4j.core.appender.JSONCompleteFileAppenderTest.testFlushAtEndOfBatch(JSONCompleteFileAppenderTest.java:54)\\n\\tat sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)\\n\\tat sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)\\n\\tat sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)\\n\\tat java.lang.reflect.Method.invoke(Method.java:606)\\n\\tat org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:47)\\n\\tat org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12)\\n\\tat org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:44)\\n\\tat org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17)\\n\\tat org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:271)\\n\\tat org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:70)\\n\\tat org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:50)\\n\\tat org.junit.runners.ParentRunner$3.run(ParentRunner.java:238)\\n\\tat org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:63)\\n\\tat org.junit.runners.ParentRunner.runChildren(ParentRunner.java:236)\\n\\tat org.junit.runners.ParentRunner.access$000(ParentRunner.java:53)\\n\\tat org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:229)\\n\\tat org.junit.internal.runners.statements.RunBefores.evaluate(RunBefores.java:26)\\n\\tat org.junit.runners.ParentRunner.run(ParentRunner.java:309)\\n\\tat org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:50)\\n\\tat org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:38)\\n\\tat org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:467)\\n\\tat org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:683)\\n\\tat org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:390)\\n\\tat org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:197)\\n"
  }
]

If complete="false", the appender does not write the JSON open array character "[" at the start of the document. and "]" and the end.

This approach enforces the independence of the JSONLayout and the appender where you embed it.

Encoding

Appenders using this layout should have their charset set to UTF-8 or UTF-16, otherwise events containing non-ASCII characters could result in corrupted log files. The default charset is UTF-8.

Pretty vs. compact JSON

By default, the JSON layout is not compact (a.k.a. not "pretty") with compact="false", which means the appender uses end-of-line characters and indents lines to format the text. If compact="true", then no end-of-line or indentation is used. Message content may contain, of course, escaped end-of-lines.

JSON Layout Parameters
Parameter Name	Type	Description
charset	String	The character set to use when converting the HTML String to a byte array. The value must be a valid Charset. If not specified, UTF-8 will be used.
compact	boolean	If true, the appender does not use end-of-lines and indentation. Defaults to false.
eventEol	boolean	If true, the appender appends an end-of-line after each record. Defaults to false. Use with eventEol=true and compact=true to get one record per line.
complete	boolean	If true, the appender includes the JSON header and footer. Defaults to false.
properties	boolean	If true, the appender includes the thread context in the generated JSON. Defaults to false.
locationInfo	boolean	If true, the appender includes the location information in the generated JSON. Defaults to false. Generating location information is an expensive operation and may impact performance. Use with caution.

HTMLLayout

The HTMLLayout generates an HTML page and adds each LogEvent to a row in a table.

HTML Layout Parameters
Parameter Name	Type	Description
charset	String	The character set to use when converting the HTML String to a byte array. The value must be a valid Charset. If not specified, the default system Charset will be used.
contentType	String	The value to assign to the Content-Type header. The default is "text/html".
locationInfo	boolean	If true, the filename and line number will be included in the HTML output. The default value is false. Generating location information is an expensive operation and may impact performance. Use with caution.
title	String	A String that will appear as the HTML title.

PatternLayout

A flexible layout configurable with pattern string. The goal of this class is to format a LogEvent and return the results. The format of the result depends on the conversion pattern.

The conversion pattern is closely related to the conversion pattern of the printf function in C. A conversion pattern is composed of literal text and format control expressions called conversion specifiers.

Note that any literal text, including Special Characters, may be included in the conversion pattern. Special Characters include \t, \n, \r, \f. Use \\ to insert a single backslash into the output.

Each conversion specifier starts with a percent sign (%) and is followed by optional format modifiers and a conversion character. The conversion character specifies the type of data, e.g. category, priority, date, thread name. The format modifiers control such things as field width, padding, left and right justification. The following is a simple example.

Let the conversion pattern be "%-5p [%t]: %m%n" and assume that the Log4j environment was set to use a PatternLayout. Then the statements

Logger logger = LogManager.getLogger("MyLogger");
logger.debug("Message 1");
logger.warn("Message 2");

would yield the output

DEBUG [main]: Message 1
WARN  [main]: Message 2

Note that there is no explicit separator between text and conversion specifiers. The pattern parser knows when it has reached the end of a conversion specifier when it reads a conversion character. In the example above the conversion specifier %-5p means the priority of the logging event should be left justified to a width of five characters.

If the pattern string does not contain a specifier to handle a Throwable being logged, parsing of the pattern will act as if the "%xEx" specifier had be added to the end of the string. To suppress formatting of the Throwable completely simply add "%ex{0}" as a specifier in the pattern string.

PatternLayout Parameters
Parameter Name	Type	Description
charset	String	The character set to use when converting the syslog String to a byte array. The String must be a valid Charset. If not specified, the default system Charset will be used.
pattern	String	A composite pattern string of one or more conversion patterns from the table below.
replace	RegexReplacement	Allows portions of the resulting String to be replaced. If configured, the replace element must specify the regular expression to match and the substitution. This performs a function similar to the RegexReplacement converter but applies to the whole message while the converter only applies to the String its pattern generates.
alwaysWriteExceptions	boolean	If `true` (it is by default) exceptions are always written even if the pattern contains no exception conversions. This means that if you do not include a way to output exceptions in your pattern, the default exception formatter will be added to the end of the pattern. Setting this to `false` disables this behavior and allows you to exclude exceptions from your pattern output.
header	String	The optional header string to include at the top of each log file.
footer	String	The optional footer string to include at the bottom of each log file.
noConsoleNoAnsi	boolean	If `true` (default is false) and `System.console()` is null, do not output ANSI escape codes.

RegexReplacement Parameters
Parameter Name	Type	Description
regex	String	A Java-compliant regular expression to match in the resulting string. See Pattern .
replacement	String	The string to replace any matched sub-strings with.

Patterns

The conversions that are provided with Log4j are:

Conversion Pattern Description

c{precision}
logger{precision}

Outputs the name of the logger that published the logging event. The logger conversion specifier can be optionally followed byprecision specifier, which consists of a decimal integer, or a pattern starting with a decimal integer.

If a precision specifier is given and it is an integer value, then only the corresponding number of right most components of the logger name will be printed. If the precision contains other non-integer characters then the name will be abbreviated based on the pattern. If the precision integer is less than one the right-most token will still be printed in full. By default the logger name is printed in full.

Conversion Pattern	Logger Name	Result
%c{1}	org.apache.commons.Foo	Foo
%c{2}	org.apache.commons.Foo	commons.Foo
%c{1.}	org.apache.commons.Foo	o.a.c.Foo
%c{1.1.~.~}	org.apache.commons.test.Foo	o.a.~.~.Foo
%c{.}	org.apache.commons.test.Foo	....Foo

C{precision}
class{precision}

Outputs the fully qualified class name of the caller issuing the logging request. This conversion specifier can be optionally followed byprecision specifier, that follows the same rules as the logger name converter.

Generating the class name of the caller (location information) is an expensive operation and may impact performance. Use with caution.

d{pattern}
date{pattern}

Outputs the date of the logging event. The date conversion specifier may be followed by a set of braces containing a date and time pattern string per SimpleDateFormat .

The predefined formats are DEFAULT, ABSOLUTE, COMPACT, DATE, ISO8601, and ISO8601_BASIC.

You can also use a set of braces containing a time zone id per java.util.TimeZone.getTimeZone. If no date format specifier is given then ISO8601 format is assumed.

Pattern	Example
%d{DEFAULT}	2012-11-02 14:34:02,781
%d{ISO8601}	2012-11-02T14:34:02,781
%d{ISO8601_BASIC}	20121102T143402,781
%d{ABSOLUTE}	14:34:02,781
%d{DATE}	02 Nov 2012 14:34:02,781
%d{COMPACT}	20121102143402781
%d{HH:mm:ss,SSS}	14:34:02,781
%d{dd MMM yyyy HH:mm:ss,SSS}	02 Nov 2012 14:34:02,781
%d{HH:mm:ss}{GMT+0}	18:34:02
%d{UNIX}	1351866842
%d{UNIX_MILLIS}	1351866842781

%d{UNIX} outputs the UNIX time in seconds. %d{UNIX_MILLIS} outputs the UNIX time in milliseconds. The UNIX time is the difference, in seconds for UNIX and in milliseconds for UNIX_MILLIS, between the current time and midnight, January 1, 1970 UTC. While the time unit is milliseconds, the granularity depends on the operating system (Windows). This is an efficient way to output the event time because only a conversion from long to String takes place, there is no Date formatting involved.

enc{pattern}
encode{pattern>

Escape newlines and HTML special characters in the specified pattern.

Allows HTML to be safely logged.

enc{pattern}
encode{pattern}

Encodes special characters such as '\n' and HTML characters to help prevent log forging and some XSS attacks that could occur when displaying logs in a web browser. Anytime user provided data is logged, this can provide a safeguard.

A typical usage would encode the message

%enc{%m}

but user input could come from other locations as well, such as the MDC

%enc{%mdc{key}}

The replaced characters are:

Character	Replacement
'\r', '\n'	Removed from the pattern
&, <, >, ", ', /	Replaced with the corresponding HTML entity

ex|exception|throwable
  {["none"
  |"full"
  |depth
  |"short"
  |"short.className"
  |"short.fileName"
  |"short.lineNumber"
  |"short.methodName"
  |"short.message"
  |"short.localizedMessage"]}

Outputs the Throwable trace bound to the LoggingEvent, by default this will output the full trace as one would normally find with a call to Throwable.printStackTrace().

You can follow the throwable conversion word with an option in the form %throwable{option}.

%throwable{short} outputs the first line of the Throwable.

%throwable{short.className} outputs the name of the class where the exception occurred.

%throwable{short.methodName} outputs the method name where the exception occurred.

%throwable{short.fileName} outputs the name of the class where the exception occurred.

%throwable{short.lineNumber} outputs the line number where the exception occurred.

%throwable{short.message} outputs the message.

%throwable{short.localizedMessage} outputs the localized message.

%throwable{n} outputs the first n lines of the stack trace.

Specifying %throwable{none} or %throwable{0} suppresses output of the exception.

F
file

Outputs the file name where the logging request was issued.

Generating the file information (location information) is an expensive operation and may impact performance. Use with caution.

highlight{pattern}{style}

Adds ANSI colors to the result of the enclosed pattern based on the current event's logging level.

The default colors for each level are:

Level	ANSI color
FATAL	Bright red
ERROR	Bright red
WARN	Yellow
INFO	Green
DEBUG	Cyan
TRACE	Black (looks dark grey)

The color names are ANSI names defined in the AnsiEscape class.

The color and attribute names and are standard, but the exact shade, hue, or value.

Color table
Intensity Code	0	1	2	3	4	5	6	7
Normal	Black	Red	Green	Yellow	Blue	Magenta	Cyan	White
Bright	Black	Red	Green	Yellow	Blue	Magenta	Cyan	White

You can use the default colors with:

%highlight{%d [%t] %-5level: %msg%n%throwable}

You can override the default colors in the optional {style} option. For example:

%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}

You can highlight only the a portion of the log event:

%d [%t] %highlight{%-5level: %msg%n%throwable}

You can style one part of the message and highlight the rest the log event:

%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}

You can also use the STYLE key to use a predefined group of colors:

%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}

The STYLE value can be one of:

Style

Description

Default

See above

Logback

Level	ANSI color
FATAL	Blinking bright red
ERROR	Bright red
WARN	Red
INFO	Blue
DEBUG	Normal
TRACE	Normal

K{key}
map{key}
MAP{key}

Outputs the entries in a MapMessage, if one is present in the event. The K conversion character can be followed by the key for the map placed between braces, as in %K{clientNumber} where clientNumber is the key. The value in the Map corresponding to the key will be output. If no additional sub-option is specified, then the entire contents of the Map key value pair set is output using a format {{key1,val1},{key2,val2}}

l
location

Outputs location information of the caller which generated the logging event.

The location information depends on the JVM implementation but usually consists of the fully qualified name of the calling method followed by the callers source the file name and line number between parentheses.

Generating location information is an expensive operation and may impact performance. Use with caution.

L
line

Outputs the line number from where the logging request was issued.

Generating line number information (location information) is an expensive operation and may impact performance. Use with caution.

m
msg
message Outputs the application supplied message associated with the logging event.

M
method

Outputs the method name where the logging request was issued.

Generating the method name of the caller (location information) is an expensive operation and may impact performance. Use with caution.

marker The name of the marker, if one is present.

Outputs the platform dependent line separator character or characters.

This conversion character offers practically the same performance as using non-portable line separator strings such as "\n", or "\r\n". Thus, it is the preferred way of specifying a line separator.

p|level{level=label, level=label, ...} p|level{length=n} p|level{lowerCase=true|false}

Outputs the level of the logging event. You provide a level name map in the form "level=value, level=value" where level is the name of the Level and value is the value that should be displayed instead of the name of the Level.

For example:

%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}

Alternatively, for the compact-minded:

%level{WARN=W, DEBUG=D, ERROR=E, TRACE=T, INFO=I}

More succinctly, for the same result as above, you can define the length of the level label:

%level{length=1}

If the length is greater than a level name length, the layout uses the normal level name.

You can combine the two kinds of options:

%level{ERROR=Error, length=2}

This give you the Error level name and all other level names of length 2.

Finally, you can output lower-case level names (the default is upper-case):

%level{lowerCase=true}

r
relative Outputs the number of milliseconds elapsed since the JVM was started until the creation of the logging event.

replace{pattern}{regex}{substitution}

Replaces occurrences of 'regex', a regular expression, with its replacement 'substitution' in the string resulting from evaluation of the pattern. For example, "%replace(%msg}{\s}{}" will remove all spaces contained in the event message.

The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords. For instance, "%replace{%logger %msg}{\.}{/}" will replace all dots in the logger or the message of the event with a forward slash.

rEx["none"|"short"|"full"|depth],[filters(packages)}
rException["none"|"short"|"full"|depth],[filters(packages)}
rThrowable["none"|"short"|"full"|depth],[filters(packages)}

The same as the %throwable conversion word but the stack trace is printed starting with the first exception that was thrown followed by each subsequent wrapping exception.

The throwable conversion word can be followed by an option in the form %rEx{short} which will only output the first line of the Throwable or %rEx{n} where the first n lines of the stacktrace will be printed. The conversion word can also be followed by "filters(packages)" where packages is a list of package names that should be suppressed from stack traces. Specifying %rEx{none} or %rEx{0} will suppress printing of the exception.

sn
sequenceNumber Includes a sequence number that will be incremented in every event. The counter is a static variable so will only be unique within applications that share the same converter Class object.

style{pattern}{ANSI style}

Uses ANSI escape sequences to style the result of the enclosed pattern. The style can consist of a comma separated list of style names from the following table.

Style Name	Description
Normal	Normal display
Bright	Bold
Dim	Dimmed or faint characters
Underline	Underlined characters
Blink	Blinking characters
Reverse	Reverse video
Hidden
Black or FG_Black	Set foreground color to black
Red or FG_Red	Set foreground color to red
Green or FG_Green	Set foreground color to green
Yellow or FG_Yellow	Set foreground color to yellow
Blue or FG_Blue	Set foreground color to blue
Magenta or FG_Magenta	Set foreground color to magenta
Cyan or FG_Cyan	Set foreground color to cyan
White or FG_White	Set foreground color to white
Default or FG_Default	Set foreground color to default (white)
BG_Black	Set background color to black
BG_Red	Set background color to red
BG_Green	Set background color to green
BG_Yellow	Set background color to yellow
BG_Blue	Set background color to blue
BG_Magenta	Set background color to magenta
BG_Cyan	Set background color to cyan
BG_White	Set background color to white

For example:

%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}

You can also combine styles:

%d %highlight{%p} %style{%logger}{bright,cyan} %C{1.} %msg%n

You can also use % with a color like %black, %blue, %cyan, and so on. For example:

%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}

t
thread Outputs the name of the thread that generated the logging event.

x
NDC Outputs the Thread Context Stack (also known as the Nested Diagnostic Context or NDC) associated with the thread that generated the logging event.

X{key}
mdc{key}
MDC{key}

Outputs the Thread Context Map (also known as the Mapped Diagnostic Context or MDC) associated with the thread that generated the logging event. The X conversion character can be followed by the key for the map placed between braces, as in %X{clientNumber} where clientNumber is the key. The value in the MDC corresponding to the key will be output. If no additional sub-option is specified, then the entire contents of the MDC key value pair set is output using a format {{key1,val1},{key2,val2}}

See the ThreadContext class for more details.

u{"RANDOM" | "TIME"}
uuid Includes either a random or a time-based UUID. The time-based UUID is a Type 1 UUID that can generate up to 10,000 unique ids per millisecond, will use the MAC address of each host, and to try to insure uniqueness across multiple JVMs and/or ClassLoaders on the same host a random number between 0 and 16,384 will be associated with each instance of the UUID generator Class and included in each time-based UUID generated. Because time-based UUIDs contain the MAC address and timestamp they should be used with care as they can cause a security vulnerability.

xEx{"none"|"short"|"full"|depth],[filters(packages)}
xException["none"|"short"|"full"|depth],[filters(packages)}
xThrowable["none"|"short"|"full"|depth],[filters(packages)}

The same as the %throwable conversion word but also includes class packaging information.

At the end of each stack element of the exception, a string containing the name of the jar file that contains the class or the directory the class is located in and the "Implementation-Version" as found in that jar's manifest will be added. If the information is uncertain, then the class packaging data will be preceded by a tilde, i.e. the '~' character.

The throwable conversion word can be followed by an option in the form %xEx{short} which will only output the first line of the Throwable or %xEx{n} where the first n lines of the stacktrace will be printed. The conversion word can also be followed by "filters(packages)" where packages is a list of package names that should be suppressed from stack traces. Specifying %xEx{none} or %xEx{0} will suppress printing of the exception.

% The sequence %% outputs a single percent sign.

By default the relevant information is output as is. However, with the aid of format modifiers it is possible to change the minimum field width, the maximum field width and justification.

The optional format modifier is placed between the percent sign and the conversion character.

The first optional format modifier is the left justification flag which is just the minus (-) character. Then comes the optional minimum field width modifier. This is a decimal constant that represents the minimum number of characters to output. If the data item requires fewer characters, it is padded on either the left or the right until the minimum width is reached. The default is to pad on the left (right justify) but you can specify right padding with the left justification flag. The padding character is space. If the data item is larger than the minimum field width, the field is expanded to accommodate the data. The value is never truncated.

This behavior can be changed using the maximum field width modifier which is designated by a period followed by a decimal constant. If the data item is longer than the maximum field, then the extra characters are removed from the beginning of the data item and not from the end. For example, it the maximum field width is eight and the data item is ten characters long, then the first two characters of the data item are dropped. This behavior deviates from the printf function in C where truncation is done from the end.

Truncation from the end is possible by appending a minus character right after the period. In that case, if the maximum field width is eight and the data item is ten characters long, then the last two characters of the data item are dropped.

Below are various format modifier examples for the category conversion specifier.

Pattern Converters
Format modifier	left justify	minimum width	maximum width	comment
%20c	false	20	none	Left pad with spaces if the category name is less than 20 characters long.
%-20c	true	20	none	Right pad with spaces if the category name is less than 20 characters long.
%.30c	NA	none	30	Truncate from the beginning if the category name is longer than 30 characters.
%20.30c	false	20	30	Left pad with spaces if the category name is shorter than 20 characters. However, if category name is longer than 30 characters, then truncate from the beginning.
%-20.30c	true	20	30	Right pad with spaces if the category name is shorter than 20 characters. However, if category name is longer than 30 characters, then truncate from the beginning.
%-20.-30c	true	20	30	Right pad with spaces if the category name is shorter than 20 characters. However, if category name is longer than 30 characters, then truncate from the end.

ANSI Styling on Windows

ANSI escape sequences are supported natively on many platforms but are not by default on Windows. To enable ANSI support simply add the Jansi jar to your application and Log4j will automatically make use of it when writing to the console.

Example Patterns

Filtered Throwables

This example shows how to filter out classes from unimportant packages in stack traces.

<properties>
  <property name="filters">org.junit,org.apache.maven,sun.reflect,java.lang.reflect</property>
</properties>
...
<PatternLayout pattern="%m%xEx{filters(${filters})}%n"/>

The result printed to the console will appear similar to:

Exception java.lang.IllegalArgumentException: IllegalArgument
at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:72) [test-classes/:?]
... suppressed 26 lines
at $Proxy0.invoke(Unknown Source)} [?:?]
... suppressed 3 lines
Caused by: java.lang.NullPointerException: null pointer
at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:71) ~[test-classes/:?]
... 30 more

ANSI Styled

The log level will be highlighted according to the event's log level. All the content that follows the level will be bright green.

<PatternLayout>
  <pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern>
</PatternLayout>

RFC5424Layout

As the name implies, the RFC5424Layout formats LogEvents in accordance with RFC 5424, the enhanced Syslog specification. Although the specification is primarily directed at sending messages via Syslog, this format is quite useful for other purposes since items are passed in the message as self-describing key/value pairs.

RFC5424Layout Parameters
Parameter Name	Type	Description
appName	String	The value to use as the APP-NAME in the RFC 5424 syslog record.
charset	String	The character set to use when converting the syslog String to a byte array. The String must be a valid Charset. If not specified, the default system Charset will be used.
enterpriseNumber	integer	The IANA enterprise number as described in RFC 5424
exceptionPattern	String	One of the conversion specifiers from PatternLayout that defines which ThrowablePatternConverter to use to format exceptions. Any of the options that are valid for those specifiers may be included. The default is to not include the Throwable from the event, if any, in the output.
facility	String	The facility is used to try to classify the message. The facility option must be set to one of "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV", "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5", "LOCAL6", or "LOCAL7". These values may be specified as upper or lower case characters.
format	String	If set to "RFC5424" the data will be formatted in accordance with RFC 5424. Otherwise, it will be formatted as a BSD Syslog record. Note that although BSD Syslog records are required to be 1024 bytes or shorter the SyslogLayout does not truncate them. The RFC5424Layout also does not truncate records since the receiver must accept records of up to 2048 bytes and may accept records that are longer.
id	String	The default structured data id to use when formatting according to RFC 5424. If the LogEvent contains a StructuredDataMessage the id from the Message will be used instead of this value.
immediateFlush	boolean	When set to true, each write will be followed by a flush. This will guarantee the data is written to disk but could impact performance.
includeMDC	boolean	Indicates whether data from the ThreadContextMap will be included in the RFC 5424 Syslog record. Defaults to true.
loggerFields	List of KeyValuePairs	Allows arbitrary PatternLayout patterns to be included as specified ThreadContext fields; no default specified. To use, include a <LoggerFields> nested element, containing one or more <KeyValuePair> elements. Each <KeyValuePair> must have a key attribute, which specifies the key name which will be used to identify the field within the MDC Structured Data element, and a value attribute, which specifies the PatternLayout pattern to use as the value.
mdcExcludes	String	A comma separated list of mdc keys that should be excluded from the LogEvent. This is mutually exclusive with the mdcIncludes attribute. This attribute only applies to RFC 5424 syslog records.
mdcIncludes	String	A comma separated list of mdc keys that should be included in the FlumeEvent. Any keys in the MDC not found in the list will be excluded. This option is mutually exclusive with the mdcExcludes attribute. This attribute only applies to RFC 5424 syslog records.
mdcRequired	String	A comma separated list of mdc keys that must be present in the MDC. If a key is not present a LoggingException will be thrown. This attribute only applies to RFC 5424 syslog records.
mdcPrefix	String	A string that should be prepended to each MDC key in order to distinguish it from event attributes. The default string is "mdc:". This attribute only applies to RFC 5424 syslog records.
mdcId	String	A required MDC ID. This attribute only applies to RFC 5424 syslog records.
messageId	String	The default value to be used in the MSGID field of RFC 5424 syslog records.
newLine	boolean	If true, a newline will be appended to the end of the syslog record. The default is false.
newLineEscape	String	String that should be used to replace newlines within the message text.

SerializedLayout

The SerializedLayout simply serializes the LogEvent into a byte array. This is useful when sending messages via JMS or via a Socket connection. The SerializedLayout accepts no parameters.

SyslogLayout

The SyslogLayout formats the LogEvent as BSD Syslog records matching the same format used by Log4j 1.2.

SyslogLayout Parameters
Parameter Name	Type	Description
charset	String	The character set to use when converting the syslog String to a byte array. The String must be a valid Charset. If not specified, the default system Charset will be used.
facility	String	The facility is used to try to classify the message. The facility option must be set to one of "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV", "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5", "LOCAL6", or "LOCAL7". These values may be specified as upper or lower case characters.
newLine	boolean	If true, a newline will be appended to the end of the syslog record. The default is false.
newLineEscape	String	String that should be used to replace newlines within the message text.

XMLLayout

Appends a series of Event elements as defined in the log4j.dtd.

Complete well-formed XML vs. fragment XML

If you configure complete="true", the appender outputs a well-formed XML document where the default namespace is the Log4j namespace "http://logging.apache.org/log4j/2.0/events". By default, with complete="false", you should include the output as an external entity in a separate file to form a well-formed XML document, in which case the appender uses namespacePrefix with a default of "log4j".

A well-formed XML document follows this pattern:

<?xml version="1.0" encoding="UTF-8"?>
<Events xmlns="http://logging.apache.org/log4j/2.0/events">
  <Event logger="com.foo.Bar" timestamp="1373436580419" level="INFO" thread="main">
    <Message><![CDATA[This is a log message 1]]></Message>
    <Marker parent="Parent Marker"><Child Marker></Marker>
  </Event>
  <Event logger="com.foo.Baz" timestamp="1373436580420" level="INFO" thread="main">
    <Message><![CDATA[This is a log message 2]]></Message>
    <Marker><The Marker Name></Marker>
  </Event>
</Events>

If complete="false", the appender does not write the XML processing instruction and the root element.

This approach enforces the independence of the XMLLayout and the appender where you embed it.

Marker

Markers are represented by a Marker element within the Event element. The Marker element appears only when a marker is used in the log message. The name of the marker's parent will be provided in the parent attribute of the Marker element. Only the leaf marker is included, not the full hierarchy.

Encoding

Appenders using this layout should have their charset set to UTF-8 or UTF-16, otherwise events containing non ASCII characters could result in corrupted log files.

Pretty vs. compact XML

By default, the XML layout is not compact (a.k.a. not "pretty") with compact="false", which means the appender uses end-of-line characters and indents lines to format the XML. If compact="true", then no end-of-line or indentation is used. Message content may contain, of course, end-of-lines.

GELF Layout

Lays out events in the Graylog Extended Log Format (GELF) 1.1.

This layout compresses JSON to GZIP or ZLIB (the compressionType) if log event data is larger than 1024 bytes (the compressionThreshold). This layout does not implement chunking.

Configure as follows to send to a Graylog2 server:

[
  <Appenders>
    <Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201">
        <GelfLayout host="someserver" compressionType="GZIP" compressionThreshold="1024">
            <KeyValuePair key="additionalField1" value="additional value 1"/>
            <KeyValuePair key="additionalField2" value="additional value 2"/>
        </GelfLayout>
    </Socket>
  </Appenders>
]

Location Information

If one of the layouts is configured with a location-related attribute like HTML locationInfo, or one of the patterns %C or class java.lang.Object, %F or %file, %l or %location, %L or %line, %M or %method, Log4j will take a snapshot of the stack, and walk the stack trace to find the location information.

This is an expensive operation: 1.3 - 5 times slower for synchronous loggers. Synchronous loggers wait as long as possible before they take this stack snapshot. If no location is required, the snapshot will never be taken.

However, asynchronous loggers need to make this decision before passing the log message to another thread; the location information will be lost after that point. The performance impact of taking a stack trace snapshot is even higher for asynchronous loggers: logging with location is 4 - 20 times slower than without location. For this reason, asynchronous loggers and asynchronous appenders do not include location information by default.

You can override the default behaviour in your logger or asynchronous appender configuration by specifying includeLocation="true".