Pattern Layout

Charset used for encoding the produced JSON into bytes

A composite pattern string of one or more Pattern converters. pattern and patternSelector are mutually exclusive, that is, only one can be specified.

This attribute supports runtime property substitution using an event evaluation context.

A component that analyzes information in the LogEvent and determines which pattern should be used to format the event. patternSelector and pattern are mutually exclusive, that is, only one can be specified.

Allows portions of the resulting String to be replaced. If configured, the replace element must specify the regular expression to match and the substitution.

If true and the user-provided pattern does not contain an exception converter, an implicit %xEX pattern is appended. 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.

The optional header to include at the top of each log file

The optional footer to include at the bottom of each log file

If true, do not output ANSI escape codes

If true and System.console() is null, do not output ANSI escape codes

Allows portions of the resulting String to be replaced. This performs a function similar to the replace converter but applies to the whole message while the converter only applies to the String its pattern generates.

It supports following attributes:

Pattern Layout can be configured with a PatternSelector to allow it to choose a pattern to use based on attributes of the log event or other factors. A PatternSelector will normally be configured with a defaultPattern attribute, which is used when other criteria don’t match, and a set of PatternMatch elements that identify the various patterns that can be selected.

Predefined PatternSelectors are as follows:

Outputs the fully qualified class name of the caller issuing the logging request

This conversion specifier can be optionally followed by a precision specifier that follows the same rules as the logger name converter.

Outputs the date of the log event

The date conversion specifier may be followed by a set of braces containing a date and time pattern string per SimpleDateFormat. The predefined named formats are:

You can also use a set of braces containing a time zone id per java.util.TimeZone#getTimeZone(String). If no date format specifier is given then the DEFAULT format is used.

You can also define custom date formats, see following examples:

%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 1970-01-01 00:00:00 (UTC). While the time unit is milliseconds, the granularity depends on the platform. 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.

There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later. Note that not all DateTimeFormatter formats are supported. Only timestamps in the formats mentioned in the table above may use the nano-of-second pattern letter n instead of the fraction-of-second pattern letter S.

Users may revert to a millisecond-precision clock when running on Java 9 by setting the log4j2.clock system property to SystemMillisClock.

Encodes and escapes special characters suitable for output in specific markup languages

By default, this encodes for HTML if only one option is specified. The second option is used to specify which encoding format should be used.

A typical usage would encode the message (i.e., %enc{%m}), but the input could come from other locations as well (e.g., from a Thread Context entry: %enc{%mdc{key}}).

Using the HTML encoding format, the following characters are replaced:

Using the XML encoding format, this follows the escaping rules specified by the XML specification:

Using the JSON encoding format, this follows the escaping rules specified by RFC 4627 section 2.5:

Using the CRLF encoding format, the following characters are replaced:

Outputs the EndOfBatch status of the log event as true or false

Replaces occurrences of a string (test) with its replacement (substitution) in the string resulting from the evaluation of the pattern:

For example, %equals{[%marker]}{[]}\{} will replace [] strings produced by events without markers with an empty string.

The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.

Outputs the Throwable attached to the log event

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.

Use {filters(packages)} where packages is a list of package names to suppress matching stack frames from stack traces.

Use {suffix(pattern)} to add the output of pattern at the end of each stack frame.

Use a {separator(…​)} as the end-of-line string, e.g., separator(\|). The default value is the line.separator system property, which is operating system dependent.

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

Different from the %throwable conversion, 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) character.

Outputs the file name where the logging request was issued

Outputs the fully qualified class name of the logger

Adds ANSI colors to the result of the enclosed pattern based on the current event’s logging level. Windows users should refer to ANSI styling on Windows.

The style parameter is a comma-separated list of the following directives:

You can use the default colors with:

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

You can highlight only a portion of the log event:

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

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

Outputs the level of the log event

You provide a level name map in the form level=value, level=value, where the 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:

Alternatively, for the compact-minded:

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

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:

This gives 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):

Outputs the line number from where the log request was issued

Outputs location information of the caller which generates the logging event

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

Outputs the name of the logger that published the log event

By default, the layout prints the logger name in full.

A logger conversion specifier can be optionally followed by a precision specifier, which consists of a decimal integer, or a pattern starting with a decimal integer.

See the table below for abbreviation examples:

Outputs the marker, if one is present

marker outputs the full name of the marker, including its parents. Whereas, markerSimpleName outputs the simple name of the marker without its parents.

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 of the map corresponding to the key will be output. If no additional sub-option is specified, then all map entries are output using a {{key1,val1},{key2,val2}} format.

Outputs the result of evaluating the given pattern and truncating the result

If the length is greater than 20, then the output will contain a trailing ellipsis. If the provided length is invalid, a default value of 100 is used.

For instance, %maxLen{%p: %c{1} - %m%notEmpty{ ⇒%ex{short}}}{160} will be limited to 160 characters with a trailing ellipsis. %maxLen{%m}{20} will be limited to 20 characters and no trailing ellipsis.

Outputs the message associated with the log event

Add {ansi} to render messages with ANSI escape codes. Windows users should refer to ANSI styling on Windows.

The default syntax for embedded ANSI codes is:

For example, to render the message Hello in green, use:

To render the message Hello in bold and red, use:

You can also define custom style names in the configuration with the syntax:

For example:

The call site can look like this:

Outputs the method name where the logging request was issued

Outputs the result of System.nanoTime() at the time the log event was created

Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty

For example:

Outputs the process ID, if supported by the underlying platform

An optional defaultValue may be specified to be shown, if the platform does not support process IDs.

Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event

Produces a string containing the requested number of instances of the specified string

For example, %repeat{*}{2} will result in the string **.

Replaces occurrences of a regular expression (regex) with its replacement (substitution) in the string resulting from the 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.

The same as the exception converter, but the stack trace is printed starting with the first exception in the causal chain that was thrown followed by each subsequent wrapping exception

The throwable conversion specifier 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 stack trace will be printed.

Specifying %rEx{none} or %rEx{0} will suppress printing of the exception.

Use filters(packages), where packages is a list of package names to suppress matching stack frames from stack traces.

Use a separator string to separate the lines of a stack trace, e.g., separator(|). The default value is the line.separator system property, which is platform dependent.

Use rEx{suffix(pattern)} to add the output of pattern to the output only when there is a Throwable to print.

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.

Use ANSI escape sequences to style the result of the enclosed pattern. The syntax of the style_expression parameter is described in Style modifiers. Windows users should also refer to ANSI styling on Windows.

For example:

You can also combine styles:

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

Outputs the Thread Context stack (aka. Nested Diagnostic Context or NDC) associated with the thread that generated the log event

Outputs the Thread Context map (aka. Mapped Diagnostic Context or MDC) associated with the thread that generated the log event

The X conversion character can be followed by one or more keys 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 a list of keys is provided, such as %X{name, number}, then each key that is present in the thread context will be output using the format {name=val1, number=val2}. The key/value pairs will be printed in the order they appear in the list.

If no sub-options are specified then the entire contents of the MDC key-value pair set is output using a format {key1=val1, key2=val2}. The key/value pairs will be printed in sorted order.

Outputs the ID of the thread that generated the log event

Outputs the name of the thread that generated the log event

Outputs the priority of the thread that generated the log event

Includes either a random or a time-based UUID

The time-based UUID is a Type 1 UUID generated using the MAC address of each host To ensure uniqueness across multiple JVMs and/or class loaders 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. See also log4j2.uuidSequence. Because time-based UUIDs contain the MAC address and timestamp, they should be used with care.

The color of the text or the background can be specified with the following style modifiers:

If your terminal supports 24-bit colors, you can specify:

ANSI escape sequences are supported natively on many platforms, but not by default on Windows. To enable ANSI support add the Jansi dependency to your application, and set the log4j2.skipJansi system property to false. This allows Log4j to use Jansi to add ANSI escape codes when writing to the console.