LOG4J2-1802: Convert layouts manual page to asciidoc

Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/f8e50945
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/f8e50945
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/f8e50945

Branch: refs/heads/master
Commit: f8e509452f6218116ba35b2b3458c9fc51c1166b
Parents: 59a9c2d
Author: Matt Sicker <boa...@gmail.com>
Authored: Sun Apr 8 21:14:47 2018 -0500
Committer: Matt Sicker <boa...@gmail.com>
Committed: Sun Apr 8 21:14:47 2018 -0500

----------------------------------------------------------------------
 src/site/asciidoc/manual/layouts.adoc | 2136 ++++++++++++++++++++++++
 src/site/xdoc/manual/layouts.xml.vm   | 2476 ----------------------------
 2 files changed, 2136 insertions(+), 2476 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/f8e50945/src/site/asciidoc/manual/layouts.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/layouts.adoc 
b/src/site/asciidoc/manual/layouts.adoc
new file mode 100644
index 0000000..d9270ae
--- /dev/null
+++ b/src/site/asciidoc/manual/layouts.adoc
@@ -0,0 +1,2136 @@
+////
+    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 <rgo...@apache.org>; Gary Gregory <ggreg...@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
+`logj-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.
+|===
+
+To include any custom field in the output, use following syntax:
+
+[source,xml]
+----
+<GelfLayout>
+  <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
+
+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.
+
+.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.
+
+|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).
+
+|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.
+
+[#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 formats are `DEFAULT`, `ABSOLUTE`, `COMPACT`, `DATE`,
+`ISO8601`, and `ISO8601_BASIC`.
+
+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.
+
+[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{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{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}
+!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
+(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.
+
+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.
+
+[#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" vairables, 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"`.

Reply via email to