////
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

         http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
////
= Layouts
Ralph Goers <rgoers@apache.org>; Gary Gregory <ggregory@apache.org>; Volkan Yazıcı <vy@apache.org>

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
https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[`Charset`]
to ensure the byte array contains correct values.

The root class for layouts that use a Charset is
`org.apache.logging.log4j.core.layout.AbstractStringLayout` where the
default is UTF-8. Each layout that extends `AbstractStringLayout` can
provide its own default. See each layout below.

A custom character encoder was added to Log4j 2.4.1 for the ISO-8859-1
and US-ASCII charsets, to bring some of the performance improvements
built-in to Java 8 to Log4j for use on Java 7. For applications that log
only ISO-8859-1 characters, specifying this charset will improve
performance significantly.

[#CSVLayouts]
== CSV Layouts

As of Log4j 2.11.0, CSV support has moved from the existing module
`log4j-core` to the new module `log4j-csv`.

This layout creates
https://en.wikipedia.org/wiki/Comma-separated_values[Comma Separated
Value (CSV)] records and requires
https://commons.apache.org/proper/commons-csv/[Apache Commons CSV] 1.4.

The CSV layout can be used in two ways: First, using
`CsvParameterLayout` to log event parameters to create a custom
database, usually to a logger and file appender uniquely configured for
this purpose. Second, using `CsvLogEventLayout` to log events to create
a database, as an alternative to using a full DBMS or using a JDBC
driver that supports the CSV format.

The `CsvParameterLayout` converts an event's parameters into a CSV
record, ignoring the message. To log CSV records, you can use the usual
Logger methods `info()`, `debug()`, and so on:

[source,java]
----
logger.info("Ignored", value1, value2, value3);
----

Which will create the CSV record:

....
value1, value2, value3
....

Alternatively, you can use a `ObjectArrayMessage`, which only carries
parameters:

[source,java]
----
logger.info(new ObjectArrayMessage(value1, value2, value3));
----

The layouts `CsvParameterLayout` and `CsvLogEventLayout` are configured
with the following parameters:

.CsvParameterLayout and CsvLogEventLayout
[cols="1m,1,4"]
|===
|Parameter Name |Type |Description

|format
|String
|One of the predefined formats: `Default`, `Excel`,
`MySQL`, `RFC4180`, `TDF`. See
https://commons.apache.org/proper/commons-csv/archives/1.4/apidocs/org/apache/commons/csv/CSVFormat.Predefined.html[CSVFormat.Predefined].

|delimiter
|Character
|Sets the delimiter of the format to the specified character.

|escape
|Character
|Sets the escape character of the format to the specified character.

|quote
|Character
|Sets the quoteChar of the format to the specified
character.

|quoteMode
|String
|Sets the output quote policy of the format to the
specified value. One of: `ALL`, `MINIMAL`, `NON_NUMERIC`, `NONE`.

|nullString
|String
|Writes null as the given nullString when writing records.

|recordSeparator
|String
|Sets the record separator of the format to the specified String.

|charset
|Charset
|The output Charset.

|header
|Sets the header to include when the stream is opened.
|Desc.

|footer
|Sets the footer to include when the stream is closed.
|Desc.
|===

Logging as a CSV events looks like this:

[source,java]
----
logger.debug("one={}, two={}, three={}", 1, 2, 3);
----

Produces a CSV record with the following fields:

1.  Time Nanos
2.  Time Millis
3.  Level
4.  Thread ID
5.  Thread Name
6.  Thread Priority
7.  Formatted Message
8.  Logger FQCN
9.  Logger Name
10. Marker
11. Thrown Proxy
12. Source
13. Context Map
14. Context Stack

....
0,1441617184044,DEBUG,main,"one=1, two=2, three=3",org.apache.logging.log4j.spi.AbstractLogger,,,,org.apache.logging.log4j.core.layout.CsvLogEventLayoutTest.testLayout(CsvLogEventLayoutTest.java:98),{},[]
....

Additional link:../runtime-dependencies.html[runtime dependencies] are
required for using CSV layouts.

[#GELFLayout]
== 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 Graylog 2.x server with UDP:

[source,xml]
----
<Appenders>
  <Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201">
      <GelfLayout host="someserver" compressionType="ZLIB" compressionThreshold="1024"/>
  </Socket>
</Appenders>
----

Configure as follows to send to a Graylog 2.x server with TCP:

[source,xml]
----
<Appenders>
  <Socket name="Graylog" protocol="tcp" host="graylog.domain.com" port="12201">
      <GelfLayout host="someserver" compressionType="OFF" includeNullDelimiter="true"/>
  </Socket>
</Appenders>
----

.GelfLayout Parameters
[cols="1m,1,4"]
|===
|Parameter Name |Type |Description

|host
|String
|The value of the `host` property (optional, defaults to local host name).

|compressionType
|`GZIP`, `ZLIB` or `OFF`
|Compression to use (optional, defaults to `GZIP`)

|compressionThreshold
|int
|Compress if data is larger than this number of bytes (optional, defaults to 1024)

|includeStacktrace
|boolean
|Whether to include full stacktrace of logged Throwables (optional, default to true).
If set to false, only the class name and message of the
https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html[Throwable]
will be included.

|includeThreadContext
|boolean
|Whether to include thread context as additional fields (optional, default to true).

|includeNullDelimiter
|boolean
|Whether to include NULL byte as delimiter after each event (optional, default to false).
Useful for Graylog GELF TCP input. Cannot be used with compression.

|messagePattern
|String
|The pattern to use to format the String. If not supplied only the text derived from the logging
message will be used. See <<PatternLayout>> for information on the pattern
strings

|threadContextExcludes
|String
|A comma separated list of ThreadContext attributes to exclude when formatting the event. This
attribute only applies when includeThreadContext="true" is specified. If threadContextIncludes
are also specified this attribute will be ignored.

|threadContextIncludes
|String
|A comma separated list of ThreadContext attributes to include when formatting the event. This
attribute only applies when includeThreadContext="true" is specified. If threadContextExcludes
are also specified this attribute will override them. ThreadContext fields specified here that
have no value will be omitted.
|===

To include any custom field in the output, use following syntax:

[source,xml]
----
<GelfLayout includeThreadContext="true" threadContextIncludes="loginId,requestId">
  <MessagePattern>%d %5p [%t] %c{1} %X{loginId, requestId} - %m%n</MessagePattern>
  <KeyValuePair key="additionalField1" value="constant value"/>
  <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
</GelfLayout>
----

Custom fields are included in the order they are declared. The values
support link:lookups.html[lookups].

See also:

* The http://docs.graylog.org/en/latest/pages/gelf.html#gelf[GELF
specification]

[#HTMLLayout]
== HTML Layout

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

.HtmlLayout Parameters
[cols="1m,1,4"]
|===
|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
http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
If not specified, this layout uses UTF-8.

|contentType
|String
|The value to assign to the Content-Type header.
The default is "text/html".

|locationInfo
|boolean
a|[[HtmlLocationInfo]]

If true, the filename and line number will be included in the HTML
output. The default value is false.

Generating link:#LocationInformation[location information] is an
expensive operation and may impact performance. Use with caution.

|title
|String
|A String that will appear as the HTML title.

|fontName
|String
|The `font-family` to use. The default is "arial,sans-serif".

|fontSize
|String
|The `font-size` to use. The default is "small".
|===

[#JSONLayout]
== JSON Layout

Appends a series of JSON events as strings serialized as bytes.

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

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

Log event follows this pattern:

[source,json]
----
{
  "instant" : {
    "epochSecond" : 1493121664,
    "nanoOfSecond" : 118000000
  },
  "thread" : "main",
  "level" : "INFO",
  "loggerName" : "HelloWorld",
  "marker" : {
    "name" : "child",
    "parents" : [ {
      "name" : "parent",
      "parents" : [ {
        "name" : "grandparent"
      } ]
    } ]
  },
  "message" : "Hello, world!",
  "thrown" : {
    "commonElementCount" : 0,
    "message" : "error message",
    "name" : "java.lang.RuntimeException",
    "extendedStackTrace" : [ {
      "class" : "logtest.Main",
      "method" : "main",
      "file" : "Main.java",
      "line" : 29,
      "exact" : true,
      "location" : "classes/",
      "version" : "?"
    } ]
  },
  "contextStack" : [ "one", "two" ],
  "endOfBatch" : false,
  "loggerFqcn" : "org.apache.logging.log4j.spi.AbstractLogger",
  "contextMap" : {
    "bar" : "BAR",
    "foo" : "FOO"
  },
  "threadId" : 1,
  "threadPriority" : 5,
  "source" : {
    "class" : "logtest.Main",
    "method" : "main",
    "file" : "Main.java",
    "line" : 29
  }
}
----

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

=== Pretty vs. compact JSON

The compact attribute determines whether the output will be "pretty" or not. The default value is "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, which will cause the output
to take less space. Of course, the message content may contain, escaped end-of-lines.

.JsonLayout Parameters
[cols="1m,1,4"]
|===
|Parameter Name |Type |Description

|charset
|String
|The character set to use when converting to a byte
array. The value must be a valid
http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[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.

|endOfLine
|String
|If set, overrides the default end-of-line string. E.g. set it to "\n" and use with eventEol=true and compact=true to have one record per line separated by "\n" instead of "\r\n". Defaults to null (i.e. not set).

|complete
|boolean
|If true, the appender includes the JSON header and
footer, and comma between records. Defaults to false.

|properties
|boolean
|If true, the appender includes the thread context
map in the generated JSON. Defaults to false.

|propertiesAsList
|boolean
|If true, the thread context map is included
as a list of map entry objects, where each entry has a "key" attribute
(whose value is the key) and a "value" attribute (whose value is the
value). Defaults to false, in which case the thread context map is
included as a simple map of key-value pairs.

|locationInfo
|boolean
a|
If true, the appender includes the location information in the generated
JSON. Defaults to false.

Generating link:#LocationInformation[location information] is an
expensive operation and may impact performance. Use with caution.

|includeStacktrace
|boolean
|If true, include full stacktrace of any logged
https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html[Throwable]
(optional, default to true).

|includeTimeMillis
|boolean
|If true, the timeMillis attribute is included in the Json payload instead of the instant. timeMillis
will contain the number of milliseconds since midnight, January 1, 1970 UTC.

|stacktraceAsString
|boolean
|Whether to format the stacktrace as a
string, and not a nested object (optional, defaults to false).

|includeNullDelimiter
|boolean
|Whether to include NULL byte as
delimiter after each event (optional, default to false).

|objectMessageAsJsonObject
|boolean
|If true, ObjectMessage is
serialized as JSON object to the "message" field of the output log.
Defaults to false.
|===

To include any custom field in the output, use following syntax:

[source,xml]
----
<JsonLayout>
  <KeyValuePair key="additionalField1" value="constant value"/>
  <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
</JsonLayout>
----

Custom fields are always last, in the order they are declared. The
values support link:lookups.html[lookups].

Additional link:../runtime-dependencies.html[runtime dependencies] are
required for using JsonLayout.

[#JSONTemplateLayout]
== JSON Template Layout

`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON
emitting layout. It encodes ``LogEvent``s according to the structure described
by the JSON template provided. For instance, given the following JSON template
modelling the https://github.com/logstash/log4j-jsonevent-layout[the official
Logstash `JSONEventLayoutV1`]

[source,json]
----
{
  "mdc": {
    "$resolver": "mdc"
  },
  "exception": {
    "exception_class": {
      "$resolver": "exception",
      "field": "className"
    },
    "exception_message": {
      "$resolver": "exception",
      "field": "message",
      "stringified": true
    },
    "stacktrace": {
      "$resolver": "exception",
      "field": "stackTrace",
      "stringified": true
    }
  },
  "line_number": {
    "$resolver": "source",
    "field": "lineNumber"
  },
  "class": {
    "$resolver": "source",
    "field": "className"
  },
  "@version": 1,
  "source_host": "${hostName}",
  "message": {
    "$resolver": "message",
    "stringified": true
  },
  "thread_name": {
    "$resolver": "thread",
    "field": "name"
  },
  "@timestamp": {
    "$resolver": "timestamp"
  },
  "level": {
    "$resolver": "level",
    "field": "name"
  },
  "file": {
    "$resolver": "source",
    "field": "fileName"
  },
  "method": {
    "$resolver": "source",
    "field": "methodName"
  },
  "logger_name": {
    "$resolver": "logger",
    "field": "name"
  }
}
----

in combination with the below Log4j configuration:

[source,xml]
----
<JsonTemplateLayout eventTemplateUri="classpath:LogstashJsonEventLayoutV1.json"/>
----

JSON Template Layout will render JSON documents as follows:

[source,json]
----
{
  "exception": {
    "exception_class": "java.lang.RuntimeException",
    "exception_message": "test",
    "stacktrace": "java.lang.RuntimeException: test\n\tat org.apache.logging.log4j.JsonTemplateLayoutDemo.main(JsonTemplateLayoutDemo.java:11)\n"
  },
  "line_number": 12,
  "class": "org.apache.logging.log4j.JsonTemplateLayoutDemo",
  "@version": 1,
  "source_host": "varlik",
  "message": "Hello, error!",
  "thread_name": "main",
  "@timestamp": "2017-05-25T19:56:23.370+02:00",
  "level": "ERROR",
  "file": "JsonTemplateLayoutDemo.java",
  "method": "main",
  "logger_name": "org.apache.logging.log4j.JsonTemplateLayoutDemo"
}
----

See link:json-template-layout.html[JSON Template Layout] page for the complete
documentation.

[#PatternLayout]
== Pattern Layout

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
[cols="1m,1,4"]
|===
|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
http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
If not specified, this layout uses the platform default character set.

|pattern
|String
|A composite pattern string of one or more conversion
patterns from the table below. Cannot be specified with a
PatternSelector.

|patternSelector
|PatternSelector
|A component that analyzes information
in the LogEvent and determines which pattern should be used to format
the event. The pattern and patternSelector parameters are mutually
exclusive.

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

|disableAnsi
|boolean
|If `true` (default is false), do not output ANSI
escape codes.

|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
https://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[Pattern].

|replacement
|String
|The string to replace any matched sub-strings with.
|===

[#Patterns]
=== Patterns

The conversions that are provided with Log4j are:

[cols="1,3a"]
|===
|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 by _precision
specifier_, which consists of a decimal integer, or a pattern starting
with a decimal integer.

When the precision specifier is an integer value, it reduces the size of
the logger name. If the number is positive, the layout prints the
corresponding number of rightmost logger name components. If negative,
the layout removes the corresponding number of leftmost logger name
components.

If the precision contains any non-integer characters, then the layout
abbreviates the name based on the pattern. If the precision integer is
less than one, the layout still prints the right-most token in full. By
default, the layout prints the logger name in full.

!===
!Conversion Pattern !Logger Name !Result

!%c{1}
!org.apache.commons.Foo
!Foo

!%c{2}
!org.apache.commons.Foo
!commons.Foo

!%c{10}
!org.apache.commons.Foo
!org.apache.commons.Foo

!%c{-1}
!org.apache.commons.Foo
!apache.commons.Foo

!%c{-2}
!org.apache.commons.Foo
!commons.Foo

!%c{-10}
!org.apache.commons.Foo
!org.apache.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
!===

|[[PatternClass]] *C*{precision} +
*class*{precision}
|Outputs the fully qualified class name of the caller issuing the logging
request. This conversion specifier can be optionally followed by
_precision specifier_, that follows the same rules as the logger name
converter.

Generating the class name of the caller
(link:#LocationInformation[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
https://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].

The predefined _named_ formats are:

[cols=",",options="header",]
!===
!Pattern !Example

!%d{DEFAULT}
!2012-11-02 14:34:02,123

!%d{DEFAULT_MICROS}
!2012-11-02 14:34:02,123456

!%d{DEFAULT_NANOS}
!2012-11-02 14:34:02,123456789

!%d{ISO8601}
!2012-11-02T14:34:02,781

!%d{ISO8601_BASIC}
!20121102T143402,781

!%d{ISO8601_OFFSET_DATE_TIME_HH}
!2012-11-02'T'14:34:02,781-07

!%d{ISO8601_OFFSET_DATE_TIME_HHMM}
!2012-11-02'T'14:34:02,781-0700

!%d{ISO8601_OFFSET_DATE_TIME_HHCMM}
!2012-11-02'T'14:34:02,781-07:00

!%d{ABSOLUTE}
!14:34:02,781

!%d{ABSOLUTE_MICROS}
!14:34:02,123456

!%d{ABSOLUTE_NANOS}
!14:34:02,123456789

!%d{DATE}
!02 Nov 2012 14:34:02,781

!%d{COMPACT}
!20121102143402781

!%d{UNIX}
!1351866842

!%d{UNIX_MILLIS}
!1351866842781
!===

You can also use a set of braces containing a time zone id per
https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[java.util.TimeZone.getTimeZone].
If no date format specifier is given then the DEFAULT format is used.

You can define custom date formats:

[cols=",",options="header",]
!===
!Pattern !Example

!%d{HH:mm:ss,SSS}
!14:34:02,123

!%d{HH:mm:ss,nnnn} to %d{HH:mm:ss,nnnnnnnnn}
!14:34:02,1234 to 14:34:02,123456789

!%d{dd MMM yyyy HH:mm:ss,SSS}
!02 Nov 2012 14:34:02,123

!%d{dd MMM yyyy HH:mm:ss,nnnn} to %d{dd MMM yyyy HH:mm:ss,nnnnnnnnn}
!02 Nov 2012 14:34:02,1234 to 02 Nov 2012 14:34:02,123456789

!%d{HH:mm:ss}{GMT+0}
!18:34:02
!===

%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
(http://msdn.microsoft.com/en-us/windows/hardware/gg463266.aspx[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.

Log4j 2.11 adds limited support for timestamps more precise than
milliseconds when running on Java 9. Note that not all
https://docs.oracle.com/javase/9/docs/api/java/time/format/DateTimeFormatter.html[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 back to a millisecond-precision clock when running on
Java 9 by setting system property `log4j2.Clock` to `SystemMillisClock`.

|*enc*{_pattern_}{[HTML\|XML\|JSON\|CRLF]} +
*encode*{_pattern_}{[HTML\|XML\|JSON\|CRLF]}
|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. This converter is particularly useful for encoding user
provided data so that the output data is not written improperly or
insecurely.

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}}`

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

!===
!Character !Replacement

!'\r', '\n'
!Converted into escaped strings "\\r" and "\\n" respectively

!&, <, >, ", ', /
!Replaced with the corresponding HTML entity
!===

Using the XML encoding format, this follows the escaping rules specified
by https://www.w3.org/TR/xml/[the XML specification]:

!===
!Character !Replacement

!&, <, >, ", '
!Replaced with the corresponding XML entity
!===

Using the JSON encoding format, this follows the escaping rules
specified by https://www.ietf.org/rfc/rfc4627.txt[RFC 4627 section 2.5]:

!===
!Character !Replacement

!U+0000 - U+001F
!\u0000 - \u001F

!Any other control characters
!Encoded into its `\uABCD` equivalent escaped code point

!"
!\"

!\
!\\
!===

For example, the pattern `{"message": "%enc{%m}{JSON}"}` could be used
to output a valid JSON document containing the log message as a string
value.

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

!===
!Character !Replacement

!'\r', '\n'
!Converted into escaped strings "\\r" and "\\n" respectively
!===

|*equals*{pattern}{test}{substitution} +
*equalsIgnoreCase*{pattern}{test}{substitution}
|Replaces occurrences of 'test', a string, with its replacement
'substitution' in the string resulting from evaluation of the pattern.
For example, "%equals{[%marker]}{[]}\{}" will replace '[]' strings
produces by events without markers with an empty string.

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

|**ex**\|**exception**\|*throwable* +
{ +
  [ "none" +
   \| "full" +
   \| depth +
   \| "short" +
   \| "short.className" +
   \| "short.fileName" +
   \| "short.lineNumber" +
   \| "short.methodName" +
   \| "short.message" +
   \| "short.localizedMessage"] +
} +
  {filters(package,package,...)} +
  {suffix(_pattern_)} +
  {separator(_separator_)}
|Outputs the Throwable trace bound to the logging 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 frames.

Use a `{separator(...)}` as the end-of-line string. For example:
`separator(\|)`. The default value is the `line.separator` system
property, which is operating system dependent.

|[[PatternFile]] *F* +
*file*
|Outputs the file name where the logging request was issued.

Generating the file information (link:#LocationInformation[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. (See Jansi link:#enable-jansi[configuration].)

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
link:../log4j-core/apidocs/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`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:

* Default: see above
* Logback:
!===
!Level !ANSI color

!FATAL !Blinking bright red

!ERROR !Bright red

!WARN !Red

!INFO !Blue

!DEBUG !Normal

!TRACE !Normal
!===

|[[PatternMap]] *K*{key} +
*map*{key} +
*MAP*{key}
|Outputs the entries in a
link:../log4j-api/apidocs/org/apache/logging/log4j/message/MapMessage.html[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}}

|[[PatternLocation]] *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 link:#LocationInformation[location information] is an
expensive operation and may impact performance. Use with caution.

|[[PatternLine]] *L* +
*line*
|Outputs the line number from where the logging request was issued.

Generating line number information (link:#LocationInformation[location
information]) is an expensive operation and may impact performance. Use
with caution.

|[[PatternMessage]] *m*{nolookups}{ansi} +
*msg*{nolookups}{ansi} +
*message*{nolookups}{ansi}
|Outputs the application supplied message associated with the logging
event.

Add `{ansi}` to render messages with ANSI escape codes (requires JAnsi,
see link:#enable-jansi[configuration].)

The default syntax for embedded ANSI codes is:

....
@\|code(,code)* text\|@
....

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

....
@\|green Hello\|@
....

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

....
@\|bold,red Warning!\|@
....

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

....
%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
....

For example:

....
%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
....

The call site can look like this:

....
logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
....

Use `{nolookups}` to log messages like `"${date:YYYY-MM-dd}"` without
using any lookups. Normally calling
`logger.info("Try ${date:YYYY-MM-dd}")` would replace the date template
`${date:YYYY-MM-dd}` with an actual date. Using `nolookups` disables
this feature and logs the message string untouched.

|[[PatternMethod]] *M* +
*method*
|Outputs the method name where the logging request was issued.

Generating the method name of the caller
(link:#LocationInformation[location information]) is an expensive
operation and may impact performance. Use with caution.

|[[PatternMarker]] *marker*
|The full name of the marker, including parents, if one is present.

|[[PatternMarkerSimpleName]] *markerSimpleName*
|The simple name of the marker (not including parents), if one is present.

|[[PatternMaxLength]] *maxLen* +
*maxLength*
|Outputs the result of evaluating the 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.

Example syntax: `%maxLen{%p: %c{1} - %m%notEmpty{ =>%ex{short}}}{160}`
will be limited to 160 characters with a trailing ellipsis. Another
example: `%maxLen{%m}{20}` will be limited to 20 characters and no
trailing ellipsis.

|[[PatternNewLine]] *n*
|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.

|[[NanoTime]] *N* +
*nano*
|Outputs the result of `System.nanoTime()` at the time the log
event was created.

|[[Process_ID]] *pid*{[defaultValue]} +
*processId*{[defaultValue]}
|Outputs the process ID if supported by the
underlying platform. An optional default value may be specified to be
shown if the platform does not support process IDs.

|[[VariablesNotEmpty]] *variablesNotEmpty*{pattern} +
*varsNotEmpty*{pattern} +
*notEmpty*{pattern}
|Outputs the result of evaluating the pattern if and only if all
variables in the pattern are not empty.

For example:

....
%notEmpty{[%marker]}
....

|[[PatternLevel]] **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}
....

|[[PatternRelative]] *r* +
*relative*
|Outputs the number of milliseconds elapsed since the JVM was
started until the creation of the logging event.

|[[PatternReplace]] *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.

|[[PatternException]] **rEx**\|**rException**\|*rThrowable* +
  { +
    ["none" \| "short" \| "full" \| depth] +
    [,filters(package,package,...)] +
    [,separator(_separator_)] +
  } +
  {ansi( +
    Key=Value,Value,... +
    Key=Value,Value,... +
    ...) +
  } +
  {suffix(_pattern_)} +
|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 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. For
example: `separator(\|)`. The default value is the `line.separator`
system property, which is operating system dependent.

Use `rEx{suffix(pattern)` to add the output of _pattern_ to the output
only when there is a throwable to print.

|[[PatternSequenceNumber]] *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.

|[[PatternStyle]] *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. (See Jansi link:#enable-jansi[configuration].)

!===
!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}
....

|[[PatternThreadId]] *T* +
*tid* +
*threadId*
|Outputs the ID of the thread that generated the logging event.

|[[PatternThreadName]] *t* +
*tn* +
*thread* +
*threadName*
|Outputs the name of the thread that generated the logging event.

|[[PatternThreadPriority]] *tp* +
*threadPriority*
|Outputs the priority of the thread that generated the logging event.

|[[PatternLoggerFqcn]] *fqcn*
|Outputs the fully qualified class name of the logger.

|[[EndOfBatch]] *endOfBatch*
|Outputs the EndOfBatch status of the logging event, as "true" or "false".

|[[PatternNDC]] *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.

|[[PatternMDC]] *X*{key[,key2...]} +
*mdc*{key[,key2...]} +
*MDC*{key[,key2...]}
|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 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 are provided, such as *%X{name, number}*, then each
key that is present in the ThreadContext 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.

See the
link:../log4j-api/apidocs/org/apache/logging/log4j/ThreadContext.html[ThreadContext]
class for more details.

|[[PatternUUID]] *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.

|[[PatternExtendedException]] **xEx**\|**xException**\|*xThrowable* +
  { +
    ["none" \| "short" \| "full" \| depth] +
    [,filters(package,package,...)] +
    [,separator(_separator_)] +
  } +
  {ansi( +
    Key=Value,Value,... +
    Key=Value,Value,... +
    ...) +
  } +
  {suffix(_pattern_)} +
|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 stack trace will be printed.
Specifying `%xEx{none}` or `%xEx{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. For
example: `separator(\|)`. The default value is the `line.separator`
system property, which is operating system dependent.

The `ansi` option renders stack traces with ANSI escapes code using the
JAnsi library. (See link:#enable-jansi[configuration].) Use `{ansi}` to
use the default color mapping. You can specify your own mappings with
`key=value` pairs. The keys are:

* Prefix
* Name
* NameMessageSeparator
* Message
* At
* CauseLabel
* Text
* More
* Suppressed
* StackTraceElement.ClassName
* StackTraceElement.ClassMethodSeparator
* StackTraceElement.MethodName
* StackTraceElement.NativeMethod
* StackTraceElement.FileName
* StackTraceElement.LineNumber
* StackTraceElement.Container
* StackTraceElement.ContainerSeparator
* StackTraceElement.UnknownSource
* ExtraClassInfo.Inexact
* ExtraClassInfo.Container
* ExtraClassInfo.ContainerSeparator
* ExtraClassInfo.Location
* ExtraClassInfo.Version

The values are names from JAnsi's
https://fusesource.github.io/jansi/documentation/api/org/fusesource/jansi/AnsiRenderer.Code.html[Code]
class like `blue`, `bg_red`, and so on (Log4j ignores case.)

The special key `StyleMapName` can be set to one of the following
predefined maps: `Spock`, `Kirk`.

As with %throwable, the *%xEx{suffix(_pattern_)* conversion will add
the output of _pattern_ to the output only if there is a throwable to
print.

|[[PatternPercentLiteral]] *%*
|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. To use zeros as the padding character prepend
the _minimum field width_ with a zero.

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

[#enable-jansi]
=== ANSI Styling on Windows

ANSI escape sequences are supported natively on many platforms but are
not by default on Windows. To enable ANSI support add the
http://jansi.fusesource.org/[Jansi] jar to your application and set
property `log4j.skipJansi` to `false`. This allows Log4j to use Jansi to
add ANSI escape codes when writing to the console.

NOTE: Prior to Log4j 2.10, Jansi was enabled by default. The fact that
Jansi requires native code means that Jansi can only be loaded by a
single class loader. For web applications this means the Jansi jar has
to be in the web container's classpath. To avoid causing problems for
web applications, Log4j will no longer automatically try to load Jansi
without explicit configuration from Log4j 2.10 onward.

=== Example Patterns

==== Filtered Throwables

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

[source,xml]
----
<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.

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

=== Pattern Selectors

The PatternLayout 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.

[#LevelPatternSelector]
==== LevelPatternSelector

The LevelPatternSelector selects patterns based on the log level of
the log event. If the Level in the log event is equal to (ignoring case)
 the name specified on the PatternMatch key attribute, then
the pattern specified on that PatternMatch element will be used.

[source,xml]
----
<PatternLayout>
  <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
    <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
  </MarkerPatternSelector>
</PatternLayout>
----

[#MarkerPatternSelector]
==== MarkerPatternSelector

The MarkerPatternSelector selects patterns based on the Marker included
in the log event. If the Marker in the log event is equal to or is an
ancestor of the name specified on the PatternMatch key attribute, then
the pattern specified on that PatternMatch element will be used.

[source,xml]
----
<PatternLayout>
  <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
    <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
  </MarkerPatternSelector>
</PatternLayout>
----

[#ScriptPatternSelector]
==== ScriptPatternSelector

The ScriptPatternSelector executes a script as descibed in the
link:../configuration.html#Scripts[Scripts] section of the Configuration
chapter. The script is passed all the properties configured in the
Properties section of the configuration, the StrSubstitutor used by the
Confguration in the "substitutor" variables, and the log event in the
"logEvent" variable, and is expected to return the value of the
PatternMatch key that should be used, or null if the default pattern
should be used.

[source,xml]
----
<PatternLayout>
  <ScriptPatternSelector defaultPattern="[%-5level] %c{1.} %C{1.}.%M.%L %msg%n">
    <Script name="BeanShellSelector" language="bsh"><![CDATA[
      if (logEvent.getLoggerName().equals("NoLocation")) {
        return "NoLocation";
      } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
        return "Flow";
      } else {
        return null;
      }]]>
    </Script>
    <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
    <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
  </ScriptPatternSelector>
</PatternLayout>
----

[#RFC5424Layout]
== RFC5424 Layout

As the name implies, the Rfc5424Layout formats LogEvents in accordance
with http://tools.ietf.org/html/rfc5424[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
[cols="1m,1,4"]
|===
|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
http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
If not specified, the default system Charset will be used.

|enterpriseNumber
|integer
|The IANA enterprise number as described in
http://tools.ietf.org/html/rfc5424#section-7.2.2[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.

|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]
== Serialized Layout

The SerializedLayout simply serializes the LogEvent into a byte array
using Java Serialization. The SerializedLayout accepts no parameters.

This layout is deprecated since version 2.9. Java Serialization has
inherent security weaknesses, using this layout is no longer
recommended. An alternative layout containing the same information is
link:#JSONLayout[JsonLayout], configured with `properties="true"`.

[#SyslogLayout]
== Syslog Layout

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

.SyslogLayout Parameters
[cols="1m,1,4"]
|===
|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
http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
If not specified, this layout uses UTF-8.

|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]
== XML Layout

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:

[source,xml]
----
<Event xmlns="http://logging.apache.org/log4j/2.0/events"
       level="INFO"
       loggerName="HelloWorld"
       endOfBatch="false"
       thread="main"
       loggerFqcn="org.apache.logging.log4j.spi.AbstractLogger"
       threadId="1"
       threadPriority="5">
  <Instant epochSecond="1493121664" nanoOfSecond="118000000"/>
  <Marker name="child">
    <Parents>
      <Marker name="parent">
        <Parents>
          <Marker name="grandparent"/>
        </Parents>
      </Marker>
    </Parents>
  </Marker>
  <Message>Hello, world!</Message>
  <ContextMap>
    <item key="bar" value="BAR"/>
    <item key="foo" value="FOO"/>
  </ContextMap>
  <ContextStack>
    <ContextStackItem>one</ContextStackItem>
    <ContextStackItem>two</ContextStackItem>
  </ContextStack>
  <Source
      class="logtest.Main"
      method="main"
      file="Main.java"
      line="29"/>
  <Thrown commonElementCount="0" message="error message" name="java.lang.RuntimeException">
    <ExtendedStackTrace>
      <ExtendedStackTraceItem
          class="logtest.Main"
          method="main"
          file="Main.java"
          line="29"
          exact="true"
          location="classes/"
          version="?"/>
    </ExtendedStackTrace>
  </Thrown>
</Event>
----

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

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

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

.XmlLayout Parameters
[cols="1m,1,4"]
|===
|Parameter Name |Type |Description

|charset
|String
|The character set to use when converting to a byte
array. The value must be a valid
https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[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.

|complete
|boolean
|If true, the appender includes the XML header and
footer. Defaults to false.

|properties
|boolean
|If true, the appender includes the thread context
map in the generated XML. Defaults to false.

|locationInfo
|boolean 
a|If true, the appender includes the location information in the generated
XML. Defaults to false.

Generating link:#LocationInformation[location information] is an
expensive operation and may impact performance. Use with caution.

|includeStacktrace
|boolean
|If true, include full stacktrace of any logged
https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html[Throwable]
(optional, default to true).

|stacktraceAsString
|boolean
|Whether to format the stacktrace as a
string, and not a nested object (optional, defaults to false).

|includeNullDelimiter
|boolean
|Whether to include NULL byte as
delimiter after each event (optional, default to false).
|===

To include any custom field in the output, use following syntax:

[source,xml]
----
<XmlLayout>
  <KeyValuePair key="additionalField1" value="constant value"/>
  <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
</XmlLayout>
----

Custom fields are always last, in the order they are declared. The
values support link:lookups.html[lookups].

Additional link:../runtime-dependencies.html[runtime dependencies] are
required for using XmlLayout.

[#YamlLayout]
== YAML Layout

Appends a series of YAML events as strings serialized as bytes.

A YAML log event follows this pattern:

[source,yaml]
----
---
instant:
 epochSecond: 1493121664
 nanoOfSecond: 118000000
thread: "main"
level: "INFO"
loggerName: "HelloWorld"
marker:
 name: "child"
 parents:
 - name: "parent"
   parents:
   - name: "grandparent"
message: "Hello, world!"
thrown:
 commonElementCount: 0
 message: "error message"
 name: "java.lang.RuntimeException"
 extendedStackTrace:
 - class: "logtest.Main"
   method: "main"
   file: "Main.java"
   line: 29
   exact: true
   location: "classes/"
   version: "?"
contextStack:
- "one"
- "two"
endOfBatch: false
loggerFqcn: "org.apache.logging.log4j.spi.AbstractLogger"
contextMap:
 bar: "BAR"
 foo: "FOO"
threadId: 1
threadPriority: 5
source:
 class: "logtest.Main"
 method: "main"
 file: "Main.java"
 line: 29
----

.YamlLayout Parameters
[cols="1m,1,4"]
|===
|Parameter Name |Type |Description

|charset
|String
|The character set to use when converting to a byte
array. The value must be a valid
https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
If not specified, UTF-8 will be used.

|properties
|boolean
|If true, the appender includes the thread context
map in the generated YAML. Defaults to false.

|locationInfo
|boolean
a|
If true, the appender includes the location information in the generated
YAML. Defaults to false.

Generating link:#LocationInformation[location information] is an
expensive operation and may impact performance. Use with caution.

|includeStacktrace
|boolean
|If true, include full stacktrace of any
logged
https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html[Throwable]
(optional, default to true).

|stacktraceAsString
|boolean
|Whether to format the stacktrace as a
string, and not a nested object (optional, defaults to false).

|includeNullDelimiter
|boolean
|Whether to include NULL byte as
delimiter after each event (optional, default to false).
|===

To include any custom field in the output, use following syntax:

[source,xml]
----
<YamlLayout>
  <KeyValuePair key="additionalField1" value="constant value"/>
  <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
</YamlLayout>
----

Custom fields are always last, in the order they are declared. The
values support link:lookups.html[lookups].

Additional link:../runtime-dependencies.html[runtime dependencies] are
required for using YamlLayout.

[#LocationInformation]
== Location Information

If one of the layouts is configured with a location-related attribute
like HTML link:#HtmlLocationInfo[locationInfo], or one of the patterns
link:#PatternClass[%C or %class], link:#PatternFile[%F or %file],
link:#PatternLocation[%l or %location], link:#PatternLine[%L or %line],
link:#PatternMethod[%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
link:../performance.html#asyncLoggingWithLocation[performance impact] of
taking a stack trace snapshot is even higher for asynchronous loggers:
logging with location is 30-100 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"`.