You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@logging.apache.org by "vy (via GitHub)" <gi...@apache.org> on 2024/06/06 11:57:07 UTC
[PR] Revamp the `Layouts` page (logging-log4j2)
vy opened a new pull request, #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645
Fixes #2527.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633693734
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
Review Comment:
Totally agreed that the current description is extremely confusing. Would you mind pushing the improvement you stated in a commit to this branch, please?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy merged PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633740014
##########
src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc:
##########
@@ -16,422 +16,479 @@
////
= JSON Template Layout
-`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON
-generating layout. It encodes ``LogEvent``s according to the structure described
-by the JSON template provided. In a nutshell, it shines with its
+JSON Template Layout is a customizable, xref:#performance[efficient], and xref:#faq-garbage-free[garbage-free] JSON generating layout.
+It encodes ``LogEvent``s according to the structure described by the JSON template provided.
+In a nutshell, it shines with its
-* Customizable JSON structure (see `eventTemplate[Uri]` and
- `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration] parameters)
+* Customizable JSON structure (see `eventTemplate[Uri]` and `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration] parameters)
-* Customizable timestamp formatting (see xref:#event-template-resolver-timestamp[]
- event template resolver)
+* Customizable timestamp formatting (see xref:#event-template-resolver-timestamp[] event template resolver)
-* Feature rich exception formatting (see xref:#event-template-resolver-exception[]
- and xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
+* Feature rich exception formatting (see xref:#event-template-resolver-exception[] and xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
* xref:manual/extending.adoc[Extensible plugin support]
* Customizable object xref:#recycling-strategy[recycling strategy]
+[TIP]
+====
+JSON Template Layout is intended for production deployments where the generated logs are expected to be delivered to an external log ingestion system such as Elasticsearch or Google Cloud Logging.
+While running tests or developing locally, you can use xref:manual/pattern-layout.adoc[] for human-readable log output.
+====
+
[#usage]
== Usage
-Adding `log4j-layout-template-json` artifact to your list of dependencies is
-enough to enable access to `JsonTemplateLayout` in your Log4j configuration:
+Adding `log4j-layout-template-json` artifact to your list of dependencies is enough to enable access to JSON Template Layout in your Log4j configuration:
+[tabs]
+====
+Maven::
++
[source,xml,subs="+attributes"]
----
-<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-layout-template-json</artifactId>
- <version>{log4j-layout-template-json-version}</version>
-</dependency>
+<project>
+
+ <!-- Assuming `log4j-bom` is imported --><!--1-->
+
+ <dependency>
+
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-layout-template-json</artifactId>
+ <scope>runtime</scope><!--2-->
+ </dependency>
+
+ </dependency>
+
+</project>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
----
+dependencies {
+
+ // Assuming `log4j-bom` is imported <1>
-For instance, given the following JSON template modelling
-https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification]
-(accessible via `classpath:EcsLayout.json`)
+ runtimeOnly // <2>
+ 'org.apache.logging.log4j:log4j-slf4j2-impl'
+
+}
+----
+====
+<1> Assuming you xref:manual/installation.adoc#bom[imported `org.apache.logging.log4j:log4j-bom`]
+<2> For applications, logging implementation dependencies are required at _runtime_.
+If you want to use JSON Template Layout for tests, you need to switch the scope to _test_.
+See xref:manual/installation.adoc[] for details.
+
+JSON Template Layout is primarily configured through an *event template* describing the structure log events should be JSON-encoded in.
+Event templates themselves are also JSON documents, where objects containing `$resolver` members, such as,
+
+[source,json]
+----
+{
+ "$resolver": "message", // <1>
+ "stringified": true // <2>
+}
+----
+<1> Indicating that this object should be replaced with the output from the xref:#event-template-resolver-message[`message` *event template resolver*]
+<2> Passing a configuration to the `message` event template resolver
+
+are interpreted by the JSON Template Layout compiler, and replaced with the referenced event or stack trace *template resolver* rendering that particular item.
+
+For instance, given the following event template stored in `MyLayout.json` in your classpath:
[source,json]
----
{
- "@timestamp": {
+ "instant": { // <1>
"$resolver": "timestamp",
"pattern": {
"format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
"timeZone": "UTC"
}
},
- "ecs.version": "1.2.0",
- "log.level": {
- "$resolver": "level",
- "field": "name"
- },
- "message": {
+ "someConstant": 1, // <2>
+ "message": { // <3>
"$resolver": "message",
"stringified": true
- },
- "process.thread.name": {
- "$resolver": "thread",
- "field": "name"
- },
- "log.logger": {
- "$resolver": "logger",
- "field": "name"
- },
- "labels": {
- "$resolver": "mdc",
- "flatten": true,
- "stringified": true
- },
- "tags": {
- "$resolver": "ndc"
- },
- "error.type": {
- "$resolver": "exception",
- "field": "className"
- },
- "error.message": {
- "$resolver": "exception",
- "field": "message"
- },
- "error.stack_trace": {
- "$resolver": "exception",
- "field": "stackTrace",
- "stackTrace": {
- "stringified": true
- }
}
}
----
+<1> Using xref:#event-template-resolver-timestamp[the `timestamp` event template resolver] to populate the `instant` field
+<2> Passing a constant that will be rendered as is
+<3> Using xref:#event-template-resolver-message[the `message` event template resolver] to populate the `message` field
-in combination with the below `log4j2.xml` configuration:
+in combination with the below layout configuration:
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.xml[`log4j2.xml`]
[source,xml]
----
-<JsonTemplateLayout eventTemplateUri="classpath:EcsLayout.json"/>
+include::example$manual/json-template-layout/usage/log4j2.xml[lines=26..26,indent=0]
----
-or with the below `log4j2.properties` configuration:
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/json-template-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
-[source,properties]
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
----
-appender.console.layout.type = JsonTemplateLayout
-appender.console.layout.eventTemplateUri = classpath:EcsLayout.json
+include::example$manual/json-template-layout/usage/log4j2.yaml[lines=22..23,indent=0]
----
-`JsonTemplateLayout` generates JSON as follows:
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+JSON Template Layout generates JSON as follows:
[source,json]
----
-{
- "@timestamp": "2017-05-25T19:56:23.370Z",
- "ecs.version": "1.2.0",
- "log.level": "ERROR",
- "message": "Hello, error!",
- "process.thread.name": "main",
- "log.logger": "org.apache.logging.log4j.JsonTemplateLayoutDemo",
- "error.type": "java.lang.RuntimeException",
- "error.message": "test",
- "error.stack_trace": "java.lang.RuntimeException: test\n\tat org.apache.logging.log4j.JsonTemplateLayoutDemo.main(JsonTemplateLayoutDemo.java:11)\n"
-}
+{"instant":"2017-05-25T19:56:23.370Z","someConstant":1,"message":"Hello, error!"} //<1>
----
+<1> JSON pretty-printing is not supported for performance reasons.
+
+Good news is *JSON Template Layout is perfectly production-ready without any configuration!*
+The event template defaults to `EcsLayout.json`, bundled in the classpath, modelling https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification].
+JSON Template Layout bundles several more xref:#event-templates[predefined event templates] modeling popular JSON-based log formats.
-[#layout-config]
-== Layout Configuration
+[#config]
+== Configuration
-`JsonTemplateLayout` is configured with the following parameters:
+This section explains how to configure JSON Template Layout plugin element in a Log4j configuration file.
-.`JsonTemplateLayout` parameters
-[cols="1m,1m,4"]
+[TIP]
+====
+Are you trying to implement your own event (or stack trace) template and looking for help on available resolvers?
+Please refer to xref:#template-config[] instead.
+====
+
+[#plugin-attrs]
+=== Plugin attributes
+
+JSON Template Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
|===
-| Parameter Name
-| Type
-| Description
-
-| charset
-| Charset
-| `Charset` used for `String` encoding
-
-| [[locationInfoEnabled]]locationInfoEnabled
-| boolean
-| toggles access to the `LogEvent` source; file name, line number, etc.
- (defaults to `false` set by `log4j.layout.jsonTemplate.locationInfoEnabled`
- property)
-
-| stackTraceEnabled
-| boolean
-| toggles access to the stack traces (defaults to `true` set by
- `log4j.layout.jsonTemplate.stackTraceEnabled` property)
-
-| eventTemplate
-| String
-| inline JSON template for rendering ``LogEvent``s (has priority over
- `eventTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplate` property)
-
-| eventTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``LogEvent``s (defaults to
- `classpath:EcsLayout.json` set by `log4j.layout.jsonTemplate.eventTemplateUri`
- property)
-
-| eventTemplateRootObjectKey
-| String
-| if present, the event template is put into a JSON object composed of a single
- member with the provided key (defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplateRootObjectKey`
- property)
-
-| eventTemplateAdditionalField
-| EventTemplateAdditionalField[]
-| additional key-value pairs appended to the root of the event template
-
-| stackTraceElementTemplate
-| String
-| inline JSON template for rendering ``StackTraceElement``s (has priority over
- `stackTraceElementTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplate` property)
-
-| stackTraceElementTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``StackTraceElement``s
- (defaults to `classpath:StackTraceElementLayout.json` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplateUri` property)
-
-| eventDelimiter
-| String
-| delimiter used for separating rendered ``LogEvent``s (defaults to
- `System.lineSeparator()` set by `log4j.layout.jsonTemplate.eventDelimiter`
- property)
-
-| nullEventDelimiterEnabled
-| boolean
-| append `\0` (`null`) character to the end of every `eventDelimiter`
- separating rendered ``LogEvent``s (defaults to `false` set by
- `log4j.layout.jsonTemplate.nullEventDelimiterEnabled` property)
-
-| [[maxStringLength]] maxStringLength
-| int
-| truncate string values longer than the specified limit (defaults to 16384 set
- by `log4j.layout.jsonTemplate.maxStringLength` property)
-
-| truncatedStringSuffix
-| String
-| suffix to append to strings truncated due to exceeding `maxStringLength`
- (defaults to `…` set by `log4j.layout.jsonTemplate.truncatedStringSuffix`
- property)
-
-| recyclerFactory
-| RecyclerFactory
-| recycling strategy that can either be `dummy`, `threadLocal`, or `queue`
- (set by `log4j.layout.jsonTemplate.recyclerFactory` property)
+|Type |`Charset`
+|Default value |`UTF-8`
+|Configuration property |`log4j.layout.jsonTemplate.charset`
|===
-[#additional-event-template-fields]
-=== Additional event template fields
+`Charset` used for encoding the produced JSON into bytes
-Additional event template fields are a convenient short-cut to add custom fields
-to a template or override the existing ones. Following configuration overrides
-the `host` field of the `GelfLayout.json` template and adds two new custom
-fields:
+[#plugin-attr-locationInfoEnabled]
+==== [[locationInfoEnabled]]`locationInfoEnabled`
-.XML configuration with additional fields
-[source,xml]
-----
-<JsonTemplateLayout eventTemplateUri="classpath:GelfLayout.json">
- <EventTemplateAdditionalField key="host" value="www.apache.org"/>
- <EventTemplateAdditionalField key="_serviceName" value="auth-service"/>
- <EventTemplateAdditionalField key="_containerId" value="6ede3f0ca7d9"/>
-</JsonTemplateLayout>
-----
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|Configuration property |`log4j.layout.jsonTemplate.locationInfoEnabled`
+|===
-The default `format` for the added new fields are `String`.
-One can also provide JSON-formatted additional fields:
+Toggles access to the `LogEvent` source; file name, line number, etc.
Review Comment:
Fixed in c5f012682d393ddb372a8b3cb0d2d184440a30f0.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1632747641
##########
src/site/antora/modules/ROOT/pages/manual/layouts.adoc:
##########
@@ -14,2120 +14,863 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-= Layouts
-An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be consuming the log event.
-In Log4j 1.x and Logback Layouts were expected to transform an event into a String.
-In Log4j 2 Layouts return a byte array.
-This allows the result of the Layout to be useful in many more types of Appenders.
-However, this means you need to configure most Layouts with a
-https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[`Charset`]
-to ensure the byte array contains correct values.
+= Layouts
-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.
+An xref:manual/appenders.adoc[appender] uses a *layout* to encode a link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[`LogEvent`] into a form that meets the needs of whatever will be consuming the log event.
+This page will try to answer following questions:
-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.
+* xref:#concerns[What are some common concerns shared by all predefined layouts?]
+* xref:#collection[Which layouts does Log4j provide?]
+* xref:#extending[How can you create custom layouts?]
-[#common-concerns]
+[#concerns]
== Common concerns
+This section introduces you to some common concerns shared by almost all xref:#collection[predefined layouts] that you need to be aware of while using them.
+
+[#charset]
+=== Character encoding
+
+All xref:#collection[predefined layouts] produce `String` that eventually get converted into a `byte[]` using the https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html[`Charset`] configured.
+While doing so, they use `UTF-8` by default.
+If you want all your log events to be formatted in a certain character encoding that is different than what the employed layout defaults to, make sure to configure the layout's character encoding as needed.
+
[#LocationInformation]
=== Location information
include::partial$manual/layouts-location-information.adoc[]
-[#CSVLayouts]
-== CSV Layouts
+[#collection]
+== Collection
+
+Log4j bundles predefined layouts to assist in several common deployment use cases.
+Let's start with shortcuts to most used ones:
+
+* Are you looking for a production-grade *JSON layout ready to be deployed to a log ingestion system* such as Elasticsearch or Google Cloud?
+Refer to xref:manual/json-template-layout.adoc[].
-As of Log4j 2.11.0, CSV support has moved from the existing module
-`log4j-core` to the new module `log4j-csv`.
+* Are you looking for a layout that encodes log events in a *human-readable format suitable for tests and local development*?
+Refer to xref:manual/pattern-layout.adoc[].
-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.
+Following sections explain all predefined layouts in detail.
-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.
+[#csv-layouts]
+=== [[CSVLayouts]] CSV Layouts
-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:
+There are two layouts performing https://en.wikipedia.org/wiki/Comma-separated_values[Comma Separated Value (CSV)] encoding:
+
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/CsvParameterLayout.html[`CsvParameterLayout`]::
+It encodes *only* the parameters of the message of a log event.
+Generated CSV records will be composed of fields denoting the message parameters.
++
+.Click here for examples
+[%collapsible]
+====
+Given the following statement
[source,java]
----
-logger.info("Ignored", value1, value2, value3);
+LOGGER.info("Record1 {} {}", "arg1", "arg2");
+LOGGER.error("Record2 {} {} {}", "arg3", "arg4", "arg5", throwable);
----
-Which will create the CSV record:
+`CsvParameterLayout` will output
-....
-value1, value2, value3
-....
+[source,text]
+----
+arg1,arg2
+arg3,arg4,arg5
+----
+
+The same can be achieved using link:../javadoc/log4j-api/org/apache/logging/log4j/message/ObjectArrayMessage.html[`ObjectArrayMessage`] as follows:
+
+[source,java]
+----
+LOGGER.info(new ObjectArrayMessage("arg1", "arg2"));
+LOGGER.info(new ObjectArrayMessage("arg3", "arg4", "arg5"));
+----
+====
-Alternatively, you can use an `ObjectArrayMessage`, which only carries parameters:
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/CsvLogEventLayout.html[`CsvLogEventLayout`]::
+It encodes the complete log event, including the formatted message.
+Generated CSV records will be composed of following fields in the given order:
++
+. Time (in nanoseconds)
+. Time (in milliseconds)
+. Level
+. Thread ID
+. Thread name
+. Thread priority
+. Message (formatted, hence including parameters)
+. Logger FQCN
+. Logger name
+. Marker
+. Throwable
+. Source
+. Thread context map
+. Thread context stack
+
++
+.Click here for examples
+[%collapsible]
+====
+Given the following statement
[source,java]
----
-logger.info(new ObjectArrayMessage(value1, value2, value3));
+LOGGER.debug("one={}, two={}, three={}", 1, 2, 3);
+----
+
+`CsvLogEventLayout` will output
+
+[source,text]
+----
+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),{},[]
----
+====
-The layouts `CsvParameterLayout` and `CsvLogEventLayout` are configured with the following parameters:
+Both `CsvParameterLayout` and `CsvLogEventLayout` are configured with the following parameters:
-.CsvParameterLayout and CsvLogEventLayout
-[cols="1m,1,4"]
+[%header,cols="1m,1m,4"]
|===
-|Parameter Name |Type |Description
+|Parameter
+|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].
+|A predefined format name (`Default`, `Excel`, `MySQL`, `RFC4180`, `TDF`, etc.) accepted by https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html[`CSVFormat`]
|delimiter
|Character
-|Sets the delimiter of the format to the specified character.
+|The field delimiter character
|escape
|Character
-|Sets the escape character of the format to the specified character.
+|The escape character
|quote
|Character
-|Sets the quoteChar of the format to the specified
-character.
+|The quote character
|quoteMode
|String
-|Sets the output quote policy of the format to the
-specified value. One of: `ALL`, `MINIMAL`, `NON_NUMERIC`, `NONE`.
+|A quote mode name (`ALL`, `ALL_NONE_NULL`, `MINIMAL`, `NON_NUMERIC`, `NONE`, etc.) accepted by https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/QuoteMode.html[`QuoteMode`]
|nullString
|String
-|Writes null as the given nullString when writing records.
+|The string to denote `null` values
|recordSeparator
|String
-|Sets the record separator of the format to the specified String.
+|The record separator string
|charset
|Charset
-|The output Charset.
+|The character encoding
|header
-|Sets the header to include when the stream is opened.
-|Desc.
+|String
+|The header to include when the stream is opened
|footer
-|Sets the footer to include when the stream is closed.
-|Desc.
+|String
+|The footer to include when the stream is closed
|===
-Logging as a CSV event 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 runtime dependencies are required for using CSV layouts
-[%collapsible,id=log4j-csv-deps]
-=====
-include::partial$manual/dependencies-log4j-csv.adoc[]
-=====
-
-[#GELFLayout]
-== GELF Layout
-
-Encodes log events in https://go2docs.graylog.org/current/getting_in_log_data/gelf.html#GELFPayloadSpecification[the GELF specification] version `1.1`.
-Compresses JSON to GZIP or ZLIB (`compressionType`) if log event data is larger than 1024 bytes (`compressionThreshold`).
-This layout does not implement chunking.
+There are additional runtime dependencies are required for using CSV layouts:
-[TIP]
+[tabs]
====
-Unless compression is needed, we advise you to use xref:manual/json-template-layout.adoc[JSON Template Layout] instead, which provides GELF layout support out of the box and offers a far richer set of features.
-====
-
-Configure as follows to send to a Graylog 2.x server with UDP:
-
-[source,xml]
+Maven::
++
+[source,xml,subs="+attributes"]
----
-<Appenders>
- <Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201">
- <GelfLayout host="someserver" compressionType="ZLIB" compressionThreshold="1024"/>
- </Socket>
-</Appenders>
+<dependency>
+ <groupId>org.apache.commons</groupId>
+ <artifactId>commons-csv</artifactId>
+ <version>{commons-csv-version}</version>
+ <scope>runtime</scope>
+</dependency>
----
-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>
-----
-
-[options="header"]
-|===
-| 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).
-| includeMapMessage | boolean | Whether to include fields from MapMessages 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.
-| 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 Throwable will be included.
-| includeThreadContext | boolean | Whether to include thread context as additional fields (optional, default to true).
-| mapMessageExcludes | String | A comma separated list of attributes from the MapMessage to exclude when formatting the event. This attribute only applies when includeMapMessage="true" is specified. If mapMessageIncludes are also specified this attribute will be ignored.
-| mapMessageIncludes | String | A comma separated list of attributes from the MapMessage to include when formatting the event. This attribute only applies when includeMapMessage="true" is specified. If mapMessageExcludes are also specified this attribute will override them. MapMessage fields specified here that have no value will be omitted.
-| mapPrefix | String | A String to prepend to all elements of the MapMessage when rendered as a field. Defaults to an empty String.
-| messagePattern | String | The pattern to use to format the String. A messagePattern and patternSelector cannot both be specified. If both are present the message pattern will be ignored and an error will be logged. If not supplied only the text derived from the logging message will be used. See PatternLayout for information on the pattern strings.
-| omitEmptyFields | boolean | If true fields which are null or are zero-length strings will not be included as a field in the Gelf JSON. This setting will not affect whether those fields appear in the message fields. The default value is false.
-| patternSelector | PatternSelector | The PatternSelector to use to format the String. A messagePattern and patternSelector cannot both be specified. If both are present the message pattern will be ignored and an error will be logged. If not supplied only the text derived from the logging message will be used. See PatternSelectors for information on how to specify a PatternSelector. 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.
-| ThreadContextPrefix | String | A String to prepend to all elements of the ThreadContextMap when rendered as a field. Defaults to an empty String.
-|===
-
-To include any custom field in the output, use following syntax:
-
-[source,xml]
+Gradle::
++
+[source,groovy,subs="+attributes"]
----
-<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>
+runtimeOnly 'org.apache.commons:commons-csv:{commons-csv-version}'
----
+====
-Custom fields are included in the order they are declared.
-The values support xref:manual/lookups.adoc[lookups].
-
-GELF Layout is garbage-free when used with `compressionType="OFF"` and as long as no additional field contains `${` (variable substitution).
-
-[#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".
-
-|datePattern
-|String
-|The date format of the logging event. The default is "JVM_ELAPSE_TIME", which outputs the milliseconds since JVM started. For other valid values, refer to the link:#PatternDate[date pattern] of PatternLayout.
-
-|timezone
-|String
-|The timezone id of the logging event. If not specified, this layout uses the https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getDefault()[java.util.TimeZone.getDefault] as the default timezone. Like link:#PatternDate[date pattern] of PatternLayout, you can use the timezone id from
-https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[java.util.TimeZone.getTimeZone].
-
-|===
-
-Configure as follows to use `dataPattern` and timezone in `HtmlLayout`:
-
-[source,xml]
-----
-<Appenders>
- <Console name="console">
- <HtmlLayout datePattern="ISO8601" timezone="GMT+0"/>
- </Console>
-</Appenders>
-----
+[#GELFLayout]
+=== GELF Layout
-[[JSONLayout]]
-== JSON Layout
+GELF Layout encodes log events in https://go2docs.graylog.org/current/getting_in_log_data/gelf.html#GELFPayloadSpecification[the GELF specification] version `1.1`.
+It can compress the output when it exceeds a certain threshold.
+This layout does not implement chunking.
[WARNING]
====
-JSON Layout is considered deprecated.
-xref:#JSONTemplateLayout[] provides more capabilities and should be used instead.
+*This layout is planned to be removed in the next major release!*
+Unless compression is needed, we advise you to use xref:manual/json-template-layout.adoc[JSON Template Layout] instead, which provides GELF Layout support out of the box and offers more capabilities and performance.
====
-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, "]" at 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
- }
-}
-----
-
-=== Pretty vs. compact JSON
+GELF Layout is configured with the following parameters:
-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 indent 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.
-
-[options="header"]
-|===
-| Parameter Name | Type | Description
-| charset | String | The character set to use when converting to a byte array. The value must be a valid `Charset`. If not specified, UTF-8 will be used.
-| compact | boolean | If true, the appender does not use end-of-lines and indentation. Defaults to false.
-| eventEol | boolean | If true, the appender appends an end-of-line after each record. Defaults to false. Use with eventEol=true and compact=true to get one record per line.
-| 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 | If true, the appender includes the location information in the generated JSON. Defaults to false. Generating location information is an expensive operation and may impact performance. Use with caution.
-| includeStacktrace | boolean | If true, include full stacktrace of any logged 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.
+[%header,cols="1m,1m,4"]
|===
+|Parameter
+|Type
+|Description
-To include any custom field in the output, use the 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 xref:manual/lookups.adoc[lookups].
-
-.Additional runtime dependencies are required for using `JsonLayout`
-[%collapsible,id=log4j-layout-json-deps]
-=====
-include::partial$manual/dependencies-log4j-layout-json.adoc[]
-=====
-
-[#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 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"
- },
- "stacktrace": {
- "$resolver": "exception",
- "field": "stackTrace",
- "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"
-}
-----
-
-.Additional runtime dependencies are required for using JSON Template Layout
-[%collapsible,id=log4j-layout-template-json-deps]
-=====
-include::partial$manual/dependencies-log4j-layout-template-json.adoc[]
-=====
-
-See xref:manual/json-template-layout.adoc[JSON Template Layout] page for the complete documentation.
-
-[id=pattern-layout]
-== [[PatternLayout]] Pattern Layout
-
-A flexible layout is configurable with a 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, and 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 been added to the end of the string.
-To suppress the 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 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="1m,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 the rightmost logger name components. If negative,
-the layout removes the corresponding number of leftmost logger name
-components. If the precision contains periods then the number before the first period
-identifies the length to be printed from items that precede tokens in the rest of the pattern.
-If the number after the first period is followed by an asterisk it indicates how many of the
-rightmost tokens will be printed in full. See the table below for abbreviation examples.
-
-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
-
-!%c{1.1.1.*}
-!org.apache.commons.test.Foo
-!o.a.c.test.Foo
-
-!%c{1.2.*}
-!org.apache.commons.test.Foo
-!o.a.c.test.Foo
-
-!%c{1.3.*}
-!org.apache.commons.test.Foo
-!o.a.commons.test.Foo
-
-!%c{1.8.*}
-!org.apache.commons.test.Foo
-!org.apache.commons.test.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.
-
-|[[PatternDate]] *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 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 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 string literals "\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 literal 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 the evaluation of the pattern.
-For example, "%equals{[%marker]}{[]}\{}" will replace '[]' strings
-produced by events without markers with an empty string.
-
-The pattern can be arbitrarily complex and in particular can contain
-multiple conversion keywords.
-
-|**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 frame.
-
-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:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`]
-class.
-
-The color and attribute names 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 portion of the log event:
-
-....
-%d [%t] %highlight{%-5level: %msg%n%throwable}
-....
-
-You can style one part of the message and highlight the rest of 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:../javadoc/log4j-api/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 of 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 generates the logging event.
-
-The location information depends on the JVM implementation but it usually
-consists of the fully qualified name of the calling method followed by
-the callers 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*\{lookups}\{ansi} +
-*msg*\{lookups}\{ansi} +
-*message\{lookups}\{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 `\{lookups}` to log messages like `"${date:YYYY-MM-dd}"` using lookups.
-using any lookups. This will replace the date template `{date:YYYY-MM-dd}`
-with an actual date. This can be confusing in many cases, and it's often both easier and
-more obvious to handle the lookup in code.
-This feature is disabled by default and the message string is logged untouched.
-
-*Note:* Users are *STRONGLY* discouraged from using the lookups option. Doing so may allow uncontrolled user input
-containing lookups to take unintended actions. In almost all cases the software developer can accomplish the same tasks
-lookups perform directly in the application code.
-
-|[[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 the level is the name of the Level
-and value is the value that should be displayed instead of the name of
-the Level.
-
-For example:
-
-....
-%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 gives you the `Error` level name and all other level names of length
-2.
-
-Finally, you can output lower-case level names (the default is upper-case):
-
-....
-%level{lowerCase=true}
-....
-
-|[[PatternRelative]] *r* +
-*relative*
-|Outputs the number of milliseconds elapsed since the JVM was
-started until the creation of the logging event.
-
-|[[PatternRepeat]] *R*\{string}\{count} +
-*repeat*\{string}\{count}
-|Produces a string containing the requested number of instances of the specified string.
-For example, "%repeat{\*}\{2}" will result in the string "**".
-
-|[[PatternReplace]] *replace*\{pattern}\{regex}\{substitution}
-|Replaces occurrences of 'regex', a regular expression, with its
-replacement 'substitution' in the string resulting from the evaluation of
-the pattern. For example, "%replace{%msg}{\s}\{}" will remove all
-spaces contained in the event message.
-
-The pattern can be arbitrarily complex and in particular, can contain
-multiple conversion keywords. For instance, "%replace{%logger
-%msg}{\.}{/}" will replace all dots in the logger or the message of
-the event with a forward slash.
-
-|[[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 the foreground color to black
-
-!Red or FG_Red
-!Set the foreground color to red
-
-!Green or FG_Green
-!Set the foreground color to green
-
-!Yellow or FG_Yellow
-!Set the foreground color to yellow
-
-!Blue or FG_Blue
-!Set the foreground color to blue
-
-!Magenta or FG_Magenta
-!Set the foreground color to magenta
-
-!Cyan or FG_Cyan
-!Set the foreground color to cyan
-
-!White or FG_White
-!Set the foreground color to white
-
-!Default or FG_Default
-!Set the foreground color to default (white)
-
-!BG_Black
-!Set the background color to black
-
-!BG_Red
-!Set the background color to red
-
-!BG_Green
-!Set the background color to green
-
-!BG_Yellow
-!Set the background color to yellow
-
-!BG_Blue
-!Set the background color to blue
-
-!BG_Magenta
-!Set the background color to magenta
-
-!BG_Cyan
-!Set the background color to cyan
+|additionalFields
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[KeyValuePair[\]]
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[`KeyValuePair`] elements denoting additional entries.
+Entry values can contain xref:manual/lookups.adoc[] using `${` syntax.
-!BG_White
-!Set the background color to white
-!===
+|compressionThreshold
+|int
+|Triggers compression if the output is larger than this number of bytes (optional, defaults to 1024)
-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 is 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:../javadoc/log4j-api/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 escape code using the
-JAnsi library. (See link:#enable-jansi[configuration].) Use `\{ansi}` to
-use the default color mapping. You can specify your 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.
-|===
+|compressionType
+|String
+|The compression to use.
+It is optional, and defaults to `GZIP`.
+Accepted values are `GZIP`, `ZLIB`, or `OFF`.
-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.
+|host
+|String
+|The value of the `host` property (optional, defaults to the local host name)
-The optional format modifier is placed between the percent sign and the conversion character.
+|includeMapMessage
+|boolean
+|Whether to include fields from xref:manual/messages.adoc#MapMessage[`MapMessage`]s as additional fields (optional, defaults to `true`)
-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.
+|includeNullDelimiter
+|boolean
+|Whether to include `NULL` byte as delimiter after each event.
+Optional and defaults to `false`.
+Useful for Graylog GELF TCP input.
+Cannot be used with compression.
-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, if 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.
+|includeStacktrace
+|boolean
+|Whether to include full stacktrace of logged ``Throwable``s.
+Optional and defaults to `true`.
+If set to `false`, only the class name and message of the `Throwable` will be included.
-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.
+|includeThreadContext
+|boolean
+|Whether to include thread context as additional fields (optional, defaults to `true`)
-Below are various format modifier examples for the category conversion specifier.
+|mapMessageExcludes
+|String
+|A comma separated list of attributes from the xref:manual/messages.adoc#MapMessage[`MapMessage`] to exclude when formatting the event.
+This attribute only applies when `includeMapMessage` is `true`.
+If `mapMessageIncludes` are also specified, this attribute will be ignored.
-.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 the 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 the 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 the category name is longer than 30
-characters, then truncate from the end.
-|===
+|mapMessageIncludes
+|String
+|A comma separated list of attributes from the xref:manual/messages.adoc#MapMessage[`MapMessage`] to include when formatting the event.
+This attribute only applies when `includeMapMessage` is `true`.
+If `mapMessageExcludes` are also specified, this attribute will override them.
+`MapMessage` fields specified here that have no value will be omitted.
-[#enable-jansi]
-=== ANSI Styling on Windows
+|mapPrefix
+|String
+|A string to prepend to all elements of the xref:manual/messages.adoc#MapMessage[`MapMessage`] when rendered as a field (optional, defaults to an empty string)
-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.
+|[[GELFLayout-messagePattern]] messagePattern
+|String
+|The pattern to use to format the `String`.
+A `messagePattern` and xref:#GELFLayout-patternSelector[`patternSelector`] cannot both be specified.
+If both are present, the message pattern will be ignored and an error will be logged.
+If not supplied, only the text derived from the log message will be used.
+See xref:manual/pattern-layout.adoc[] for information on the pattern strings.
-NOTE: Before 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.
+|omitEmptyFields
+|boolean
+|If `true`, fields which are null or are zero-length strings will not be included as a field in the produced JSON.
+This setting will not affect if those fields appear in the message fields.
+The default value is `false`.
+
+|[[GELFLayout-patternSelector]] patternSelector
+|xref:manual/pattern-layout.adoc#plugin-element-PatternSelector[PatternSelector]
+|The `PatternSelector` to use to format the `String`.
+A xref:#GELFLayout-messagePattern[`messagePattern`] and `patternSelector` cannot both be specified.
+If both are present, the message pattern will be ignored and an error will be logged.
+If not supplied, only the text derived from the logging message will be used.
+See xref:manual/pattern-layout.adoc#plugin-element-PatternSelector[`PatternSelector`] for information on how to specify a `PatternSelector`.
+See xref:manual/pattern-layout.adoc[] for information on the pattern strings.
+
+|threadContextExcludes
+|String
+|A comma separated list of xref:manual/thread-context.adoc[] map keys to exclude when formatting the event.
+This attribute only applies when `includeThreadContext` is `true`.
+If `threadContextIncludes` are also specified, this attribute will be ignored.
-=== Example Patterns
+|threadContextIncludes
+|String
+|A comma separated list of xref:manual/thread-context.adoc[] map keys to include when formatting the event.
+This attribute only applies when `includeThreadContext` is `true`.
+If `threadContextExcludes` are also, specified this attribute will override them.
+Thread context fields specified here that have no value will be omitted.
-==== Filtered Throwables
+|threadContextPrefix
+|String
+|A string to prepend to all elements of the xref:manual/thread-context.adoc[] map when rendered as a field (defaults to an empty string)
+|===
-This example shows how to filter out classes from unimportant packages in stack traces.
+GELF Layout is garbage-free if `compressionType` is `OFF` and there are no additional fields containing `${`.
+.Example configurations
+[%collapsible]
+====
+[tabs]
+=====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.xml[`log4j2.xml`]
[source,xml]
----
-<Configuration>
- <properties>
- <property name="filters">org.junit,org.apache.maven,sun.reflect,java.lang.reflect</property>
- </properties>
- <!-- ... -->
- <PatternLayout pattern="%m%xEx{filters(${filters})}%n"/>
-</Configuration>
+include::example$manual/gelf-layout/log4j2.xml[lines=26..41,indent=0]
----
-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
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/gelf-layout/log4j2.json[lines=5..48,indent=0]
+----
-The log level will be highlighted according to the event's log level.
-All the content that follows the level will be bright green.
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/gelf-layout/log4j2.yaml[lines=21..53,indent=0]
+----
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.properties[`log4j2.properties`]
[source,xml]
----
-<PatternLayout>
- <pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern>
-</PatternLayout>
+include::example$manual/gelf-layout/log4j2.properties[lines=17..48,indent=0]
----
+=====
+<1> Configuration with additional key value pairs
+<2> Configuration for appending to a Graylog server using TCP
+<3> Configuration for appending to a Graylog server using UDP
+====
-[#PatternSelectors]
-=== Pattern Selectors
+[#HTMLLayout]
+=== HTML Layout
-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.
+HTML Layout generates an HTML page, and adds each log event to a row in a table.
+It is configured with the following parameters:
-[#LevelPatternSelector]
-==== LevelPatternSelector
+[%header,cols="1m,1m,4"]
+|===
+|Parameter
+|Type
+|Description
-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.
+|charset
+|String
+|The character encoding
-[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>
-----
+|contentType
+|String
+|The `Content-Type` header value (defaults to `text/html`)
-[#MarkerPatternSelector]
-==== MarkerPatternSelector
+|datePattern
+|String
+|The date format of the log event.
+The default is `JVM_ELAPSE_TIME`, which outputs the milliseconds since JVM started.
+For other valid values, refer to xref:manual/pattern-layout.adoc#converter-date[the `date` conversion specifier of Pattern Layout].
-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.
+|fontName
+|String
+|The `font-family` (defaults to `arial,sans-serif`)
-[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>
-----
+|fontSize
+|String
+|The `font size` (defaults to `small`)
-[#ScriptPatternSelector]
-==== ScriptPatternSelector
+|locationInfo
+|boolean
+|If `true`, the xref:#LocationInformation[source location information] be included (defaults to `false`)
-The ScriptPatternSelector executes a script as described in the
-xref:manual/scripts.adoc[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 Configuration 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.
+|timezone
+|String
+|The time zone ID of the log event.
+If not specified, this layout uses the https://docs.oracle.com/javase/8/docs/api/java/util/TimeZone.html#getDefault()[`TimeZone.getDefault()`] as the default.
+You can use time zone IDs supported by https://docs.oracle.com/javase/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`TimeZone.getTimeZone(String)`].
-[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>
-----
+|title
+|String
+|The HTML page title
+|===
-[#PatternLayout-gcfree]
-=== Garbage-free configuration
+[[JSONLayout]]
+=== JSON Layout
-PatternLayout with the following limited set of conversion patterns is
-garbage-free. Format modifiers to control such things as field width,
-padding, left and right justification will not generate garbage.
+JSON Layout encodes a log event into JSON.
-[cols="1m,2"]
-|===
-|Conversion Pattern |Description
+[WARNING]
+====
+JSON Layout is considered deprecated.
+It is succeeded by xref:#JSONTemplateLayout[] providing more capabilities and efficiency.
+====
-|%c\{precision}, %logger\{precision}
-|Logger name
+.Click for an example output
+[%collapsible]
+====
+[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
+ }
+}
+----
+====
-|%d, %date
-a|
-Note: Only the predefined date formats are garbage-free: (millisecond
-separator may be either a comma ',' or a period '.')
+JSON Layout is configured with the following parameters:
-[cols="1m,1"]
-!===
-!Pattern !Example
+[%header,cols="1m,1m,4"]
+|===
+|Parameter Name
+|Type
+|Description
-!%d\{DEFAULT}
-!2012-11-02 14:34:02,781
+|additionalFields
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[KeyValuePair[\]]
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[`KeyValuePair`] elements denoting additional entries.
+Entry values can contain xref:manual/lookups.adoc[] using `${` syntax.
-!%d\{ISO8601}
-!2012-11-02T14:34:02,781
+|charset
+|String
+|The character encoding (defaults to `UTF-8`)
-!%d\{ISO8601_BASIC}
-!20121102T143402,781
+|compact
+|boolean
+|If `true`, does not use `endOfLine` and indentation.
+This feature is also referred to as _pretty-printing_ too.
+It defaults to `false`.
-!%d\{ABSOLUTE}
-!14:34:02,781
+|complete
+|boolean
+|
+If `true`, uses `header` and `footer`, and places comma between records – this leads to a well-formed JSON document given `header` and `footer` defaults to `[` and `]`, respectively.
+It defaults to `false`.
-!%d\{DATE}
-!02 Nov 2012 14:34:02,781
+|endOfLine
+|String
+|If set, overrides the default end-of-line string.
+For instance, 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`.
+It is not set by default.
-!%d\{COMPACT}
-!20121102143402781
+|eventEol
+|boolean
+|If `true`, appends an `endOfLine` after each log event, even if `compact=true`.
+It defaults to `false`.
+Use with `eventEol=true` and `compact=true` to get one record per line.
-!%d{HH:mm:ss,SSS}
-!14:34:02,781
+|footer
+|String
+|The footer to include when the stream is closed and `complete=true` (defaults to `]`)
-!%d{dd MMM yyyy HH:mm:ss,SSS}
-!02 Nov 2012 14:34:02,781
+|header
+|String
+|The header to include when the stream is opened and `complete=true` (defaults to `[`)
-!%d{HH:mm:ss}{GMT+0}
-!18:34:02
+|includeNullDelimiter
+|boolean
+|If `true`, a NULL byte will suffix each encoded log event (defaults to `false`)
-!%d\{UNIX}
-!1351866842
+|includeStacktrace
+|boolean
+|If `true`, include full stacktrace of any logged `Throwable` (defaults to `true`)
-!%d\{UNIX_MILLIS}
-!1351866842781
-!===
+|includeTimeMillis
+|boolean
+|If `true`, a `timeMillis` attribute is included in the JSON payload instead of the `instant`.
+`timeMillis` will contain the number of milliseconds since 1970-01-01T00:00:00Z.
-|%enc\{pattern}, %encode\{pattern}
-|Encodes special characters such as
-'\n' and HTML characters to help prevent log forging and some XSS
-attacks that could occur when displaying logs in a web browser -
-garbage-free since 2.8
+|locationInfo
+|boolean
+|If `true`, the appender includes the xref:#LocationInformation[source location information] in the generated JSON (defaults to `false`)
-|%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 - garbage-free since 2.8
+|objectMessageAsJsonObject
+|boolean
+|If `true`, xref:manual/messages.adoc#ObjectMessage[`ObjectMessage`] is serialized as JSON object to the `message` field of the output log (defaults to `false`)
-|%highlight\{pattern}\{style}
-|Adds ANSI colors - garbage-free since 2.7
-(unless nested pattern is not garbage free)
+|properties
+|boolean
+|If `true`, the appender includes the xref:manual/thread-context.adoc[] map in the generated JSON (defaults to `false`)
-|%K\{key}, %map\{key}, %MAP\{key}
-|Outputs the entries in a
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[MapMessage],
-if one is present in the event - garbage-free since 2.8.
+|propertiesAsList
+|boolean
+|If `true`, the xref:manual/thread-context.adoc[] map is included as a list of map entry objects, where each entry is denoted as a JSON object containg `key` and `value` fields.
+It defaults to `false`, in which case the thread context map is included as a simple map of key-value pairs.
-|%m, %msg, %message
-|Log message (garbage-free unless message text
-contains '${')
+|stacktraceAsString
+|boolean
+|If `true`, the stacktrace will be formatted as `String`, and not a nested object (optional, defaults to `false`)
+|===
-|%marker
-|The full name of the marker (including parents) - garbage-free
-since 2.8
+Additional runtime dependencies are required for using JSON Layout:
-|%markerSimpleName
-|The simple name of the marker (not including
-parents)
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<dependency>
+ <groupId>com.fasterxml.jackson.core</groupId>
+ <artifactId>jackson-databind</artifactId>
+ <version>{jackson-version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
-|%maxLen, %maxLength
-|Truncates another pattern to some max number of
-characters - garbage-free since 2.8
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:{jackson-version}'
+----
+====
-|%n
-|The platform dependent line separator
+[#JSONTemplateLayout]
+=== JSON Template Layout
-|%N, %nano
-|System.nanoTime() when the event was logged
+JSON Template Layout is a customizable, efficient, and garbage-free JSON generating layout.
+It encodes ``LogEvent``s according to the structure described by the JSON template provided.
+For instance, given the following event template stored in `MyLayout.json` in your classpath:
-|%notEmpty\{pattern}, %varsNotEmpty\{pattern},
-%variablesNotEmpty\{pattern}
-|Outputs the result of evaluating the
-pattern if and only if all variables in the pattern are not empty -
-garbage-free since 2.8
+[source,json]
+----
+{
+ "instant": { // <1>
+ "$resolver": "timestamp",
+ "pattern": {
+ "format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
+ "timeZone": "UTC"
+ }
+ },
+ "someConstant": 1, // <2>
+ "message": { // <3>
+ "$resolver": "message",
+ "stringified": true
+ }
+}
+----
+<1> Using the `timestamp` event template resolver to populate the `instant` field
+<2> Passing a constant that will be rendered as is
+<3> Using the `message` event template resolver to populate the `message` field
-|%p, %level
-|The level of the logging event
+in combination with the below layout configuration:
-|%r, %relative
-|The number of milliseconds elapsed since the JVM was
-started until the creation of the logging event - garbage-free since 2.8
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
-|%sn, %sequenceNumber
-|A sequence number that will be incremented in
-every event - garbage-free since 2.8
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/json-template-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
-|%style\{pattern}{ANSI style}
-|Style the message - garbage-free since
-2.7 (unless nested pattern is not garbage free)
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
-|%T, %tid, %threadId
-|The ID of the thread that generated the logging
-event
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
-|%t, %tn, %thread, %threadName
-|The name of the thread that generated
-the logging event
+JSON Template Layout generates JSON as follows:
-|%tp
-|The priority of the thread that generated the logging event
+[source,json]
+----
+{"instant":"2017-05-25T19:56:23.370Z","someConstant":1,"message":"Hello, error!"} //<1>
+----
+<1> JSON pretty-printing is not supported for performance reasons.
-|%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 -
-garbage-free since 2.8
+Good news is JSON Template Layout is perfectly production-ready without any configuration!
+It bundles several predefined event templates modeling popular JSON-based log formats.
-|literal text
-|Garbage-free unless literal contains '${' (variable
-substitution)
-|===
+Read more on xref:manual/json-template-layout.adoc[]...
-Other PatternLayout conversion patterns, and other Layouts may be
-updated to avoid creating temporary objects in future releases. (Patches
-welcome!)
+[id=pattern-layout]
+=== [[PatternLayout]] Pattern Layout
-NOTE: Logging exceptions and stack traces will create temporary
-objects with any layout. (However, Layouts will only create these
-temporary objects when an exception actually occurs.) We haven't figured
-out a way to log exceptions and stack traces without creating temporary
-objects. That is unfortunate, but you probably still want to log them
-when they happen.
+Pattern Layout is a customizable, efficient, garbage-free, and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
-[NOTE]
+[IMPORTANT]
====
-patterns containing regular expressions and lookups for property
-substitution will result in temporary objects being created during
-steady-state logging.
-
-Including location information is done by walking the stacktrace of an
-exception, which creates temporary objects, so the following patterns
-are not garbage-free:
-
-* %C, %class - Class Name
-* %F, %file - File Location
-* %l, %location - Location
-* %L, %line - Line Location
-* %M, %method - Method Location
-
-Also, the pattern converters for formatting Throwables are not
-garbage-free:
-
-* %ex, %exception, %throwable - The Throwable trace bound to the
-LoggingEvent
-* %rEx, %rException %rThrowable - Same as %ex but with wrapping
-exceptions
-* %xEx, %xException, %xThrowable - Same as %ex but with class packaging
-information
-* %u, %uuid - Creates a new random or time-based UUID while formatting
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
====
-[#PatternLayout-performance]
-=== Performance
+A conversion pattern is composed of literal text and format control expressions.
+For instance, given the `%-5p [%t]: %m%n` pattern, following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
-Great effort has been put into the efficiency of Pattern Layout.
-To get the most out of it, mind the following checklist:
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
-* Enable xref:manual/garbagefree.adoc[garbage-free logging]
-* Mind xref:#PatternLayout-gcfree[the garbage footprint of features you use]
-* Don't give too much slack to xref:manual/systemproperties.adoc#log4j2.layoutStringBuilderMaxSize[`log4j2
-.layoutStringBuilderMaxSize`] and try to keep it relatively tight
+Read more on xref:manual/pattern-layout.adoc[]...
[#RFC5424Layout]
-== RFC5424 Layout
+=== RFC 5424 Layout
+
+RFC 5424 Layout encodes log events according to https://datatracker.ietf.org/doc/html/rfc5424#section-6[the Syslog message format described in RFC 5424].
-As the name implies, the Rfc5424Layout formats LogEvents by 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.
+[NOTE]
+====
+RFC 5424 obsoletes RFC 3164, implemented by xref:#SyslogLayout[].
+====
+
+RFC 5424 Layout is configured with the following parameters:
-.Rfc5424Layout Parameters
-[cols="1m,1,4"]
+[%header,cols="1m,1m,4"]
|===
-|Parameter Name |Type |Description
+|Parameter
+|Type
+|Description
|appName
|String
-|The value to use as the APP-NAME in the RFC 5424
-syslog record.
+|The `APP-NAME` field as described in RFC 5424
|charset
|String
-|The character set to use when converting the syslog
-String to a byte array. The String must be 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.
+|The character encoding (defaults to `UTF-8`)
|enterpriseNumber
|integer
-|The IANA enterprise number as described in
-http://tools.ietf.org/html/rfc5424#section-7.2.2[RFC 5424]
+|The `enterpriseId` parameter as described in RFC 5424 (defaults to `32473`)
Review Comment:
```suggestion
|
The `enterpriseId` parameter as described in RFC 5424.
If missing, `32473` will be used, which is https://www.rfc-editor.org/rfc/rfc5612.html#section-2[reserved for documentation use].
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1631301216
##########
src/site/antora/modules/ROOT/pages/manual/layouts.adoc:
##########
@@ -14,2120 +14,863 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-= Layouts
-An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be consuming the log event.
-In Log4j 1.x and Logback Layouts were expected to transform an event into a String.
-In Log4j 2 Layouts return a byte array.
-This allows the result of the Layout to be useful in many more types of Appenders.
-However, this means you need to configure most Layouts with a
-https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[`Charset`]
-to ensure the byte array contains correct values.
+= Layouts
-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.
+An xref:manual/appenders.adoc[appender] uses a *layout* to encode a link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[`LogEvent`] into a form that meets the needs of whatever will be consuming the log event.
+This page will try to answer following questions:
-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.
+* xref:#concerns[What are some common concerns shared by all predefined layouts?]
+* xref:#collection[Which layouts does Log4j provide?]
+* xref:#extending[How can you create custom layouts?]
-[#common-concerns]
+[#concerns]
== Common concerns
+This section introduces you to some common concerns shared by almost all xref:#collection[predefined layouts] that you need to be aware of while using them.
+
+[#charset]
+=== Character encoding
+
+All xref:#collection[predefined layouts] produce `String` that eventually get converted into a `byte[]` using the https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html[`Charset`] configured.
+While doing so, they use `UTF-8` by default.
Review Comment:
The default is not always `UTF-8`: structured layouts such as XML, JSON, YAML and BSD Syslog use `UTF-8` as default, but `PatternLayout` uses the default system encoding.
##########
src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc:
##########
@@ -954,25 +978,28 @@ Resolve the argument coming right after `--userId`:
"key": "--userId"
}
----
+====
[#event-template-resolver-map]
===== `map`
-Resolves ``MapMessage``s. See link:#map-resolver-template[Map Resolver Template]
-for details.
+Resolves ``MapMessage``s.
+See link:#map-resolver-template[] for details.
Review Comment:
Should we use:
```suggestion
See <<map-resolver-template>> for details.
```
instead? Currently the text describing the link is `#map-resolver-template`.
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
Review Comment:
Could we explain here the general syntax of a converter pattern, e.g. we could write:
```
%d{dateSpecifier}[{timezone}]
```
to indicate that the `d` patter converter has a **required** `dateSpecifier` parameter and an **optional** `timeZone` parameter.
I would be also useful to explain how to escape a pattern specifier to have a **literal** `%d{something}` in your log.
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
Review Comment:
```suggestion
equals{pattern}{test}{substitution}
```
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%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
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+You can enable xref:manual/lookups.adoc[] using `\{lookups}` and log messages like `${date:YYYY-MM-dd}` using lookups.
+This will replace the date template `YYYY-MM-dd` with an actual date.
+This can be confusing in many cases, and it's often both easier and more obvious to handle the lookup in code.
+This feature is disabled by default and the message string is logged untouched.
+
+[WARNING]
+====
+Users are strongly discouraged from using the lookups option.
+Doing so may allow uncontrolled user input containing lookups to take unintended actions.
+====
+
+[#converter-method]
+==== Method
+
+Outputs the method name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MethodLocationPatternConverter.html[`MethodLocationPatternConverter`] specifier grammar
+[source,text]
+----
+M
+method
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the method name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-nano]
+==== Nanoseconds
+
+Outputs the result of `System.nanoTime()` at the time the log event was created
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NanoTimePatternConverter.html[`NanoTimePatternConverter`] specifier grammar
+[source,text]
+----
+N
+nano
+----
+
+[#converter-not-empty]
+==== Not empty
+
+Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/VariablesNotEmptyReplacementConverter.html[`VariablesNotEmptyReplacementConverter`] specifier grammar
+[source,text]
+----
+variablesNotEmpty{pattern}
+varsNotEmpty{pattern}
+notEmpty{pattern}
+----
+
+For example:
+
+[source,text]
+----
+%notEmpty{[%marker]}
+----
+
+[#converter-pid]
+==== Process ID
+
+Outputs the process ID, if supported by the underlying platform
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ProcessIdPatternConverter.html[`ProcessIdPatternConverter`] specifier grammar
+[source,text]
+----
+pid{defaultValue}
+processId{defaultValue}
+----
+
+An optional `defaultValue` may be specified to be shown, if the platform does not support process IDs.
+
+[#converter-relative]
+==== Relative
+
+Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RelativeTimePatternConverter.html[`RelativeTimePatternConverter`] specifier grammar
+[source,text]
+----
+r
+relative
+----
+
+[#converter-repeat]
+==== Repeat
+
+Produces a string containing the requested number of instances of the specified string
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RepeatPatternConverter.html[`RepeatPatternConverter`] specifier grammar
+[source,text]
+----
+R{string}{count}
+repeat{string}{count}
+----
+
+For example, `%repeat{\*}\{2}` will result in the string `**`.
+
+[#converter-replace]
+==== Replace
+
+Replaces occurrences of a regular expression (`regex`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RegexReplacementConverter.html[`RegexReplacementConverter`] specifier grammar
+[source,text]
+----
+replace{pattern}{regex}{substitution}
+----
+
+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.
+
+[#converter-rootException]
+==== Root exception
+
+The same as xref:#converter-exception[the `exception` converter], but the stack trace is printed starting with the first exception in the causal chain that was thrown followed by each subsequent wrapping exception
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.html[`RootThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+rEx|rException|rThrowable
+ {
+ ["none" | "short" | "full" | depth]
+ [,filters(package,package,...)]
+ [,separator(separator)]
+ }
+ {ansi(
+ Key=Value,Value,...
+ Key=Value,Value,...
+ ...)
+ }
+ {suffix(pattern)}
+----
+
+The throwable conversion specifier can be followed by an option in the form `%rEx\{short}`, which will only output the first line of the `Throwable`, or `%rEx\{n}`, where the first `n` lines of the stack trace will be printed.
+
+Specifying `%rEx\{none}` or `%rEx\{0}` will suppress printing of the exception.
+
+Use `filters(packages)`, where `packages` is a list of package names to suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace, e.g., `separator(|)`.
+The default value is the `line.separator` system property, which is platform dependent.
+
+Use `rEx{suffix(pattern)}` to add the output of `pattern` to the output only when there is a `Throwable` to print.
+
+[#converter-seq]
+==== Sequence number
+
+Includes a sequence number that will be incremented in every event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/SequenceNumberPatternConverter.html[`SequenceNumberPatternConverter`] specifier grammar
+[source,text]
+----
+sn
+sequenceNumber
+----
+
+The counter is a static variable, so will only be unique within applications that share the same converter class object.
+
+[#converter-style]
+==== Style
+
+Use ANSI escape sequences to style the result of the enclosed pattern.
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/StyleConverter.html[`StyleConverter`] specifier grammar
+[source,text]
+----
+style{pattern}{ANSI style}
+----
+
+The style can consist of a comma-separated list of style names from the following table:
+
+[%header,cols="2m,3"]
+|===
+|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 the foreground color to black
+
+|Red or FG_Red
+|Set the foreground color to red
+
+|Green or FG_Green
+|Set the foreground color to green
+
+|Yellow or FG_Yellow
+|Set the foreground color to yellow
+
+|Blue or FG_Blue
+|Set the foreground color to blue
+
+|Magenta or FG_Magenta
+|Set the foreground color to magenta
+
+|Cyan or FG_Cyan
+|Set the foreground color to cyan
+
+|White or FG_White
+|Set the foreground color to white
+
+|Default or FG_Default
+|Set the foreground color to default (white)
+
+|BG_Black
+|Set the background color to black
+
+|BG_Red
+|Set the background color to red
+
+|BG_Green
+|Set the background color to green
+
+|BG_Yellow
+|Set the background color to yellow
+
+|BG_Blue
+|Set the background color to blue
+
+|BG_Magenta
+|Set the background color to magenta
+
+|BG_Cyan
+|Set the background color to cyan
+
+|BG_White
+|Set the background color to white
+|===
+
+For example:
+
+[source,text]
+----
+%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}
+----
+
+You can also combine styles:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}
+----
+
+[#converter-thread-context-stack]
+==== Thread context stack
+
+Outputs the xref:manual/thread-context.adoc[] stack (aka. Nested Diagnostic Context or NDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NdcPatternConverter.html[`NdcPatternConverter`] specifiers grammar
+[source,text]
+----
+x
+NDC
+----
+
+[#converter-thread-context-map]
+==== Thread context map
+
+Outputs the xref:manual/thread-context.adoc[] map (aka. Mapped Diagnostic Context or MDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MdcPatternConverter.html[`MdcPatternConverter`] specifiers grammar
+[source,text]
+----
+X{key[,key2...]}
+mdc{key[,key2...]}
+MDC{key[,key2...]}
+----
+
+The *X* conversion character can be followed by one or more keys for the map placed between braces, as in `%X\{clientNumber}`, where `clientNumber` is the key.
+The value in the MDC corresponding to the key will be output.
+
+If a list of keys is provided, such as `%X{name, number}`, then each key that is present in the thread context will be output using the format `{name=val1, number=val2}`.
+The key/value pairs will be printed in the order they appear in the list.
+
+If no sub-options are specified then the entire contents of the MDC key-value pair set is output using a format `{key1=val1, key2=val2}`.
+The key/value pairs will be printed in sorted order.
+
+[#converter-thread-id]
+==== Thread ID
+
+Outputs the ID of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadIdPatternConverter.html[`ThreadIdPatternConverter`] specifiers grammar
+[source,text]
+----
+T
+tid
+threadId
+----
+
+[#converter-thread-name]
+==== Thread name
+
+Outputs the name of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadNamePatternConverter.html[`ThreadNamePatternConverter`] specifier grammar
+[source,text]
+----
+t
+tn
+thread
+threadName
+----
+
+[#converter-thread-priority]
+==== Thread priority
+
+Outputs the priority of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadPriorityPatternConverter.html[`ThreadPriorityPatternConverter`] specifier grammar
+[source,text]
+----
+tp
+threadPriority
+----
+
+[#converter-uuid]
+==== UUID
+
+Includes either a random or a time-based UUID
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/UuidConverter.html[`UuidConverter`] specifier grammar
+[source,text]
+----
+u{RANDOM|TIME}
+uuid{RANDOM|TIME}
+----
+
+The time-based UUID is a Type 1 UUID generated using the MAC address of each host
+To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated.
Review Comment:
```suggestion
To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated.
See also xref:manual/systemproperties.adoc#log4j2.uuidSequence[`log4j2.uuidSequence`].
```
##########
src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc:
##########
@@ -16,422 +16,479 @@
////
= JSON Template Layout
-`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON
-generating layout. It encodes ``LogEvent``s according to the structure described
-by the JSON template provided. In a nutshell, it shines with its
+JSON Template Layout is a customizable, xref:#performance[efficient], and xref:#faq-garbage-free[garbage-free] JSON generating layout.
+It encodes ``LogEvent``s according to the structure described by the JSON template provided.
+In a nutshell, it shines with its
-* Customizable JSON structure (see `eventTemplate[Uri]` and
- `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration] parameters)
+* Customizable JSON structure (see `eventTemplate[Uri]` and `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration] parameters)
-* Customizable timestamp formatting (see xref:#event-template-resolver-timestamp[]
- event template resolver)
+* Customizable timestamp formatting (see xref:#event-template-resolver-timestamp[] event template resolver)
-* Feature rich exception formatting (see xref:#event-template-resolver-exception[]
- and xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
+* Feature rich exception formatting (see xref:#event-template-resolver-exception[] and xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
* xref:manual/extending.adoc[Extensible plugin support]
* Customizable object xref:#recycling-strategy[recycling strategy]
+[TIP]
+====
+JSON Template Layout is intended for production deployments where the generated logs are expected to be delivered to an external log ingestion system such as Elasticsearch or Google Cloud Logging.
+While running tests or developing locally, you can use xref:manual/pattern-layout.adoc[] for human-readable log output.
+====
+
[#usage]
== Usage
-Adding `log4j-layout-template-json` artifact to your list of dependencies is
-enough to enable access to `JsonTemplateLayout` in your Log4j configuration:
+Adding `log4j-layout-template-json` artifact to your list of dependencies is enough to enable access to JSON Template Layout in your Log4j configuration:
+[tabs]
+====
+Maven::
++
[source,xml,subs="+attributes"]
----
-<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-layout-template-json</artifactId>
- <version>{log4j-layout-template-json-version}</version>
-</dependency>
+<project>
+
+ <!-- Assuming `log4j-bom` is imported --><!--1-->
+
+ <dependency>
+
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-layout-template-json</artifactId>
+ <scope>runtime</scope><!--2-->
+ </dependency>
+
+ </dependency>
+
+</project>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
----
+dependencies {
+
+ // Assuming `log4j-bom` is imported <1>
-For instance, given the following JSON template modelling
-https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification]
-(accessible via `classpath:EcsLayout.json`)
+ runtimeOnly // <2>
+ 'org.apache.logging.log4j:log4j-slf4j2-impl'
+
+}
+----
+====
+<1> Assuming you xref:manual/installation.adoc#bom[imported `org.apache.logging.log4j:log4j-bom`]
+<2> For applications, logging implementation dependencies are required at _runtime_.
+If you want to use JSON Template Layout for tests, you need to switch the scope to _test_.
+See xref:manual/installation.adoc[] for details.
+
+JSON Template Layout is primarily configured through an *event template* describing the structure log events should be JSON-encoded in.
+Event templates themselves are also JSON documents, where objects containing `$resolver` members, such as,
+
+[source,json]
+----
+{
+ "$resolver": "message", // <1>
+ "stringified": true // <2>
+}
+----
+<1> Indicating that this object should be replaced with the output from the xref:#event-template-resolver-message[`message` *event template resolver*]
+<2> Passing a configuration to the `message` event template resolver
+
+are interpreted by the JSON Template Layout compiler, and replaced with the referenced event or stack trace *template resolver* rendering that particular item.
+
+For instance, given the following event template stored in `MyLayout.json` in your classpath:
[source,json]
----
{
- "@timestamp": {
+ "instant": { // <1>
"$resolver": "timestamp",
"pattern": {
"format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
"timeZone": "UTC"
}
},
- "ecs.version": "1.2.0",
- "log.level": {
- "$resolver": "level",
- "field": "name"
- },
- "message": {
+ "someConstant": 1, // <2>
+ "message": { // <3>
"$resolver": "message",
"stringified": true
- },
- "process.thread.name": {
- "$resolver": "thread",
- "field": "name"
- },
- "log.logger": {
- "$resolver": "logger",
- "field": "name"
- },
- "labels": {
- "$resolver": "mdc",
- "flatten": true,
- "stringified": true
- },
- "tags": {
- "$resolver": "ndc"
- },
- "error.type": {
- "$resolver": "exception",
- "field": "className"
- },
- "error.message": {
- "$resolver": "exception",
- "field": "message"
- },
- "error.stack_trace": {
- "$resolver": "exception",
- "field": "stackTrace",
- "stackTrace": {
- "stringified": true
- }
}
}
----
+<1> Using xref:#event-template-resolver-timestamp[the `timestamp` event template resolver] to populate the `instant` field
+<2> Passing a constant that will be rendered as is
+<3> Using xref:#event-template-resolver-message[the `message` event template resolver] to populate the `message` field
-in combination with the below `log4j2.xml` configuration:
+in combination with the below layout configuration:
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.xml[`log4j2.xml`]
[source,xml]
----
-<JsonTemplateLayout eventTemplateUri="classpath:EcsLayout.json"/>
+include::example$manual/json-template-layout/usage/log4j2.xml[lines=26..26,indent=0]
----
-or with the below `log4j2.properties` configuration:
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/json-template-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
-[source,properties]
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
----
-appender.console.layout.type = JsonTemplateLayout
-appender.console.layout.eventTemplateUri = classpath:EcsLayout.json
+include::example$manual/json-template-layout/usage/log4j2.yaml[lines=22..23,indent=0]
----
-`JsonTemplateLayout` generates JSON as follows:
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+JSON Template Layout generates JSON as follows:
[source,json]
----
-{
- "@timestamp": "2017-05-25T19:56:23.370Z",
- "ecs.version": "1.2.0",
- "log.level": "ERROR",
- "message": "Hello, error!",
- "process.thread.name": "main",
- "log.logger": "org.apache.logging.log4j.JsonTemplateLayoutDemo",
- "error.type": "java.lang.RuntimeException",
- "error.message": "test",
- "error.stack_trace": "java.lang.RuntimeException: test\n\tat org.apache.logging.log4j.JsonTemplateLayoutDemo.main(JsonTemplateLayoutDemo.java:11)\n"
-}
+{"instant":"2017-05-25T19:56:23.370Z","someConstant":1,"message":"Hello, error!"} //<1>
----
+<1> JSON pretty-printing is not supported for performance reasons.
+
+Good news is *JSON Template Layout is perfectly production-ready without any configuration!*
+The event template defaults to `EcsLayout.json`, bundled in the classpath, modelling https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification].
+JSON Template Layout bundles several more xref:#event-templates[predefined event templates] modeling popular JSON-based log formats.
-[#layout-config]
-== Layout Configuration
+[#config]
+== Configuration
-`JsonTemplateLayout` is configured with the following parameters:
+This section explains how to configure JSON Template Layout plugin element in a Log4j configuration file.
-.`JsonTemplateLayout` parameters
-[cols="1m,1m,4"]
+[TIP]
+====
+Are you trying to implement your own event (or stack trace) template and looking for help on available resolvers?
+Please refer to xref:#template-config[] instead.
+====
+
+[#plugin-attrs]
+=== Plugin attributes
+
+JSON Template Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
|===
-| Parameter Name
-| Type
-| Description
-
-| charset
-| Charset
-| `Charset` used for `String` encoding
-
-| [[locationInfoEnabled]]locationInfoEnabled
-| boolean
-| toggles access to the `LogEvent` source; file name, line number, etc.
- (defaults to `false` set by `log4j.layout.jsonTemplate.locationInfoEnabled`
- property)
-
-| stackTraceEnabled
-| boolean
-| toggles access to the stack traces (defaults to `true` set by
- `log4j.layout.jsonTemplate.stackTraceEnabled` property)
-
-| eventTemplate
-| String
-| inline JSON template for rendering ``LogEvent``s (has priority over
- `eventTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplate` property)
-
-| eventTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``LogEvent``s (defaults to
- `classpath:EcsLayout.json` set by `log4j.layout.jsonTemplate.eventTemplateUri`
- property)
-
-| eventTemplateRootObjectKey
-| String
-| if present, the event template is put into a JSON object composed of a single
- member with the provided key (defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplateRootObjectKey`
- property)
-
-| eventTemplateAdditionalField
-| EventTemplateAdditionalField[]
-| additional key-value pairs appended to the root of the event template
-
-| stackTraceElementTemplate
-| String
-| inline JSON template for rendering ``StackTraceElement``s (has priority over
- `stackTraceElementTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplate` property)
-
-| stackTraceElementTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``StackTraceElement``s
- (defaults to `classpath:StackTraceElementLayout.json` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplateUri` property)
-
-| eventDelimiter
-| String
-| delimiter used for separating rendered ``LogEvent``s (defaults to
- `System.lineSeparator()` set by `log4j.layout.jsonTemplate.eventDelimiter`
- property)
-
-| nullEventDelimiterEnabled
-| boolean
-| append `\0` (`null`) character to the end of every `eventDelimiter`
- separating rendered ``LogEvent``s (defaults to `false` set by
- `log4j.layout.jsonTemplate.nullEventDelimiterEnabled` property)
-
-| [[maxStringLength]] maxStringLength
-| int
-| truncate string values longer than the specified limit (defaults to 16384 set
- by `log4j.layout.jsonTemplate.maxStringLength` property)
-
-| truncatedStringSuffix
-| String
-| suffix to append to strings truncated due to exceeding `maxStringLength`
- (defaults to `…` set by `log4j.layout.jsonTemplate.truncatedStringSuffix`
- property)
-
-| recyclerFactory
-| RecyclerFactory
-| recycling strategy that can either be `dummy`, `threadLocal`, or `queue`
- (set by `log4j.layout.jsonTemplate.recyclerFactory` property)
+|Type |`Charset`
+|Default value |`UTF-8`
+|Configuration property |`log4j.layout.jsonTemplate.charset`
|===
-[#additional-event-template-fields]
-=== Additional event template fields
+`Charset` used for encoding the produced JSON into bytes
-Additional event template fields are a convenient short-cut to add custom fields
-to a template or override the existing ones. Following configuration overrides
-the `host` field of the `GelfLayout.json` template and adds two new custom
-fields:
+[#plugin-attr-locationInfoEnabled]
+==== [[locationInfoEnabled]]`locationInfoEnabled`
-.XML configuration with additional fields
-[source,xml]
-----
-<JsonTemplateLayout eventTemplateUri="classpath:GelfLayout.json">
- <EventTemplateAdditionalField key="host" value="www.apache.org"/>
- <EventTemplateAdditionalField key="_serviceName" value="auth-service"/>
- <EventTemplateAdditionalField key="_containerId" value="6ede3f0ca7d9"/>
-</JsonTemplateLayout>
-----
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|Configuration property |`log4j.layout.jsonTemplate.locationInfoEnabled`
+|===
-The default `format` for the added new fields are `String`.
-One can also provide JSON-formatted additional fields:
+Toggles access to the `LogEvent` source; file name, line number, etc.
Review Comment:
```suggestion
Toggles access to the `LogEvent` source; file name, line number, etc.
See also xref:manual/layouts.adoc#LocationInformation[location information].
```
##########
src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc:
##########
@@ -992,39 +1019,41 @@ Resolve the names of the marker's parents:
"field": "parents"
}
----
+====
[#event-template-resolver-mdc]
===== `mdc`
-Resolves Mapped Diagnostic Context (MDC), aka. Thread Context Data. See
-link:#map-resolver-template[Map Resolver Template] for details.
+Resolves the xref:manual/thread-context.adoc[thread context] map, aka. Mapped Diagnostic Context (MDC).
+See link:#map-resolver-template[] for details.
Review Comment:
```suggestion
See <<map-resolver-template>> for details.
```
##########
src/site/antora/modules/ROOT/pages/manual/layouts.adoc:
##########
@@ -14,2120 +14,863 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-= Layouts
-An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be consuming the log event.
-In Log4j 1.x and Logback Layouts were expected to transform an event into a String.
-In Log4j 2 Layouts return a byte array.
-This allows the result of the Layout to be useful in many more types of Appenders.
-However, this means you need to configure most Layouts with a
-https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[`Charset`]
-to ensure the byte array contains correct values.
+= Layouts
-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.
+An xref:manual/appenders.adoc[appender] uses a *layout* to encode a link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[`LogEvent`] into a form that meets the needs of whatever will be consuming the log event.
+This page will try to answer following questions:
-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.
+* xref:#concerns[What are some common concerns shared by all predefined layouts?]
+* xref:#collection[Which layouts does Log4j provide?]
+* xref:#extending[How can you create custom layouts?]
-[#common-concerns]
+[#concerns]
== Common concerns
+This section introduces you to some common concerns shared by almost all xref:#collection[predefined layouts] that you need to be aware of while using them.
+
+[#charset]
+=== Character encoding
+
+All xref:#collection[predefined layouts] produce `String` that eventually get converted into a `byte[]` using the https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html[`Charset`] configured.
+While doing so, they use `UTF-8` by default.
+If you want all your log events to be formatted in a certain character encoding that is different than what the employed layout defaults to, make sure to configure the layout's character encoding as needed.
+
[#LocationInformation]
=== Location information
include::partial$manual/layouts-location-information.adoc[]
-[#CSVLayouts]
-== CSV Layouts
+[#collection]
+== Collection
+
+Log4j bundles predefined layouts to assist in several common deployment use cases.
+Let's start with shortcuts to most used ones:
+
+* Are you looking for a production-grade *JSON layout ready to be deployed to a log ingestion system* such as Elasticsearch or Google Cloud?
+Refer to xref:manual/json-template-layout.adoc[].
-As of Log4j 2.11.0, CSV support has moved from the existing module
-`log4j-core` to the new module `log4j-csv`.
+* Are you looking for a layout that encodes log events in a *human-readable format suitable for tests and local development*?
+Refer to xref:manual/pattern-layout.adoc[].
-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.
+Following sections explain all predefined layouts in detail.
-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.
+[#csv-layouts]
+=== [[CSVLayouts]] CSV Layouts
-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:
+There are two layouts performing https://en.wikipedia.org/wiki/Comma-separated_values[Comma Separated Value (CSV)] encoding:
+
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/CsvParameterLayout.html[`CsvParameterLayout`]::
+It encodes *only* the parameters of the message of a log event.
+Generated CSV records will be composed of fields denoting the message parameters.
++
+.Click here for examples
+[%collapsible]
+====
+Given the following statement
[source,java]
----
-logger.info("Ignored", value1, value2, value3);
+LOGGER.info("Record1 {} {}", "arg1", "arg2");
+LOGGER.error("Record2 {} {} {}", "arg3", "arg4", "arg5", throwable);
----
-Which will create the CSV record:
+`CsvParameterLayout` will output
-....
-value1, value2, value3
-....
+[source,text]
+----
+arg1,arg2
+arg3,arg4,arg5
+----
+
+The same can be achieved using link:../javadoc/log4j-api/org/apache/logging/log4j/message/ObjectArrayMessage.html[`ObjectArrayMessage`] as follows:
+
+[source,java]
+----
+LOGGER.info(new ObjectArrayMessage("arg1", "arg2"));
+LOGGER.info(new ObjectArrayMessage("arg3", "arg4", "arg5"));
+----
+====
-Alternatively, you can use an `ObjectArrayMessage`, which only carries parameters:
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/CsvLogEventLayout.html[`CsvLogEventLayout`]::
+It encodes the complete log event, including the formatted message.
+Generated CSV records will be composed of following fields in the given order:
++
+. Time (in nanoseconds)
+. Time (in milliseconds)
+. Level
+. Thread ID
+. Thread name
+. Thread priority
+. Message (formatted, hence including parameters)
+. Logger FQCN
+. Logger name
+. Marker
+. Throwable
+. Source
+. Thread context map
+. Thread context stack
+
++
+.Click here for examples
+[%collapsible]
+====
+Given the following statement
[source,java]
----
-logger.info(new ObjectArrayMessage(value1, value2, value3));
+LOGGER.debug("one={}, two={}, three={}", 1, 2, 3);
+----
+
+`CsvLogEventLayout` will output
+
+[source,text]
+----
+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),{},[]
----
+====
-The layouts `CsvParameterLayout` and `CsvLogEventLayout` are configured with the following parameters:
+Both `CsvParameterLayout` and `CsvLogEventLayout` are configured with the following parameters:
-.CsvParameterLayout and CsvLogEventLayout
-[cols="1m,1,4"]
+[%header,cols="1m,1m,4"]
|===
-|Parameter Name |Type |Description
+|Parameter
+|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].
+|A predefined format name (`Default`, `Excel`, `MySQL`, `RFC4180`, `TDF`, etc.) accepted by https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html[`CSVFormat`]
|delimiter
|Character
-|Sets the delimiter of the format to the specified character.
+|The field delimiter character
|escape
|Character
-|Sets the escape character of the format to the specified character.
+|The escape character
|quote
|Character
-|Sets the quoteChar of the format to the specified
-character.
+|The quote character
|quoteMode
|String
-|Sets the output quote policy of the format to the
-specified value. One of: `ALL`, `MINIMAL`, `NON_NUMERIC`, `NONE`.
+|A quote mode name (`ALL`, `ALL_NONE_NULL`, `MINIMAL`, `NON_NUMERIC`, `NONE`, etc.) accepted by https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/QuoteMode.html[`QuoteMode`]
|nullString
|String
-|Writes null as the given nullString when writing records.
+|The string to denote `null` values
|recordSeparator
|String
-|Sets the record separator of the format to the specified String.
+|The record separator string
|charset
|Charset
-|The output Charset.
+|The character encoding
|header
-|Sets the header to include when the stream is opened.
-|Desc.
+|String
+|The header to include when the stream is opened
|footer
-|Sets the footer to include when the stream is closed.
-|Desc.
+|String
+|The footer to include when the stream is closed
|===
-Logging as a CSV event 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 runtime dependencies are required for using CSV layouts
-[%collapsible,id=log4j-csv-deps]
-=====
-include::partial$manual/dependencies-log4j-csv.adoc[]
-=====
-
-[#GELFLayout]
-== GELF Layout
-
-Encodes log events in https://go2docs.graylog.org/current/getting_in_log_data/gelf.html#GELFPayloadSpecification[the GELF specification] version `1.1`.
-Compresses JSON to GZIP or ZLIB (`compressionType`) if log event data is larger than 1024 bytes (`compressionThreshold`).
-This layout does not implement chunking.
+There are additional runtime dependencies are required for using CSV layouts:
-[TIP]
+[tabs]
====
-Unless compression is needed, we advise you to use xref:manual/json-template-layout.adoc[JSON Template Layout] instead, which provides GELF layout support out of the box and offers a far richer set of features.
-====
-
-Configure as follows to send to a Graylog 2.x server with UDP:
-
-[source,xml]
+Maven::
++
+[source,xml,subs="+attributes"]
----
-<Appenders>
- <Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201">
- <GelfLayout host="someserver" compressionType="ZLIB" compressionThreshold="1024"/>
- </Socket>
-</Appenders>
+<dependency>
+ <groupId>org.apache.commons</groupId>
+ <artifactId>commons-csv</artifactId>
+ <version>{commons-csv-version}</version>
+ <scope>runtime</scope>
+</dependency>
----
-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>
-----
-
-[options="header"]
-|===
-| 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).
-| includeMapMessage | boolean | Whether to include fields from MapMessages 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.
-| 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 Throwable will be included.
-| includeThreadContext | boolean | Whether to include thread context as additional fields (optional, default to true).
-| mapMessageExcludes | String | A comma separated list of attributes from the MapMessage to exclude when formatting the event. This attribute only applies when includeMapMessage="true" is specified. If mapMessageIncludes are also specified this attribute will be ignored.
-| mapMessageIncludes | String | A comma separated list of attributes from the MapMessage to include when formatting the event. This attribute only applies when includeMapMessage="true" is specified. If mapMessageExcludes are also specified this attribute will override them. MapMessage fields specified here that have no value will be omitted.
-| mapPrefix | String | A String to prepend to all elements of the MapMessage when rendered as a field. Defaults to an empty String.
-| messagePattern | String | The pattern to use to format the String. A messagePattern and patternSelector cannot both be specified. If both are present the message pattern will be ignored and an error will be logged. If not supplied only the text derived from the logging message will be used. See PatternLayout for information on the pattern strings.
-| omitEmptyFields | boolean | If true fields which are null or are zero-length strings will not be included as a field in the Gelf JSON. This setting will not affect whether those fields appear in the message fields. The default value is false.
-| patternSelector | PatternSelector | The PatternSelector to use to format the String. A messagePattern and patternSelector cannot both be specified. If both are present the message pattern will be ignored and an error will be logged. If not supplied only the text derived from the logging message will be used. See PatternSelectors for information on how to specify a PatternSelector. 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.
-| ThreadContextPrefix | String | A String to prepend to all elements of the ThreadContextMap when rendered as a field. Defaults to an empty String.
-|===
-
-To include any custom field in the output, use following syntax:
-
-[source,xml]
+Gradle::
++
+[source,groovy,subs="+attributes"]
----
-<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>
+runtimeOnly 'org.apache.commons:commons-csv:{commons-csv-version}'
----
+====
-Custom fields are included in the order they are declared.
-The values support xref:manual/lookups.adoc[lookups].
-
-GELF Layout is garbage-free when used with `compressionType="OFF"` and as long as no additional field contains `${` (variable substitution).
-
-[#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".
-
-|datePattern
-|String
-|The date format of the logging event. The default is "JVM_ELAPSE_TIME", which outputs the milliseconds since JVM started. For other valid values, refer to the link:#PatternDate[date pattern] of PatternLayout.
-
-|timezone
-|String
-|The timezone id of the logging event. If not specified, this layout uses the https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getDefault()[java.util.TimeZone.getDefault] as the default timezone. Like link:#PatternDate[date pattern] of PatternLayout, you can use the timezone id from
-https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[java.util.TimeZone.getTimeZone].
-
-|===
-
-Configure as follows to use `dataPattern` and timezone in `HtmlLayout`:
-
-[source,xml]
-----
-<Appenders>
- <Console name="console">
- <HtmlLayout datePattern="ISO8601" timezone="GMT+0"/>
- </Console>
-</Appenders>
-----
+[#GELFLayout]
+=== GELF Layout
-[[JSONLayout]]
-== JSON Layout
+GELF Layout encodes log events in https://go2docs.graylog.org/current/getting_in_log_data/gelf.html#GELFPayloadSpecification[the GELF specification] version `1.1`.
+It can compress the output when it exceeds a certain threshold.
+This layout does not implement chunking.
[WARNING]
====
-JSON Layout is considered deprecated.
-xref:#JSONTemplateLayout[] provides more capabilities and should be used instead.
+*This layout is planned to be removed in the next major release!*
+Unless compression is needed, we advise you to use xref:manual/json-template-layout.adoc[JSON Template Layout] instead, which provides GELF Layout support out of the box and offers more capabilities and performance.
====
-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, "]" at 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
- }
-}
-----
-
-=== Pretty vs. compact JSON
+GELF Layout is configured with the following parameters:
-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 indent 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.
-
-[options="header"]
-|===
-| Parameter Name | Type | Description
-| charset | String | The character set to use when converting to a byte array. The value must be a valid `Charset`. If not specified, UTF-8 will be used.
-| compact | boolean | If true, the appender does not use end-of-lines and indentation. Defaults to false.
-| eventEol | boolean | If true, the appender appends an end-of-line after each record. Defaults to false. Use with eventEol=true and compact=true to get one record per line.
-| 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 | If true, the appender includes the location information in the generated JSON. Defaults to false. Generating location information is an expensive operation and may impact performance. Use with caution.
-| includeStacktrace | boolean | If true, include full stacktrace of any logged 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.
+[%header,cols="1m,1m,4"]
|===
+|Parameter
+|Type
+|Description
-To include any custom field in the output, use the 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 xref:manual/lookups.adoc[lookups].
-
-.Additional runtime dependencies are required for using `JsonLayout`
-[%collapsible,id=log4j-layout-json-deps]
-=====
-include::partial$manual/dependencies-log4j-layout-json.adoc[]
-=====
-
-[#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 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"
- },
- "stacktrace": {
- "$resolver": "exception",
- "field": "stackTrace",
- "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"
-}
-----
-
-.Additional runtime dependencies are required for using JSON Template Layout
-[%collapsible,id=log4j-layout-template-json-deps]
-=====
-include::partial$manual/dependencies-log4j-layout-template-json.adoc[]
-=====
-
-See xref:manual/json-template-layout.adoc[JSON Template Layout] page for the complete documentation.
-
-[id=pattern-layout]
-== [[PatternLayout]] Pattern Layout
-
-A flexible layout is configurable with a 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, and 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 been added to the end of the string.
-To suppress the 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 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="1m,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 the rightmost logger name components. If negative,
-the layout removes the corresponding number of leftmost logger name
-components. If the precision contains periods then the number before the first period
-identifies the length to be printed from items that precede tokens in the rest of the pattern.
-If the number after the first period is followed by an asterisk it indicates how many of the
-rightmost tokens will be printed in full. See the table below for abbreviation examples.
-
-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
-
-!%c{1.1.1.*}
-!org.apache.commons.test.Foo
-!o.a.c.test.Foo
-
-!%c{1.2.*}
-!org.apache.commons.test.Foo
-!o.a.c.test.Foo
-
-!%c{1.3.*}
-!org.apache.commons.test.Foo
-!o.a.commons.test.Foo
-
-!%c{1.8.*}
-!org.apache.commons.test.Foo
-!org.apache.commons.test.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.
-
-|[[PatternDate]] *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 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 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 string literals "\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 literal 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 the evaluation of the pattern.
-For example, "%equals{[%marker]}{[]}\{}" will replace '[]' strings
-produced by events without markers with an empty string.
-
-The pattern can be arbitrarily complex and in particular can contain
-multiple conversion keywords.
-
-|**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 frame.
-
-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:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`]
-class.
-
-The color and attribute names 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 portion of the log event:
-
-....
-%d [%t] %highlight{%-5level: %msg%n%throwable}
-....
-
-You can style one part of the message and highlight the rest of 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:../javadoc/log4j-api/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 of 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 generates the logging event.
-
-The location information depends on the JVM implementation but it usually
-consists of the fully qualified name of the calling method followed by
-the callers 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*\{lookups}\{ansi} +
-*msg*\{lookups}\{ansi} +
-*message\{lookups}\{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 `\{lookups}` to log messages like `"${date:YYYY-MM-dd}"` using lookups.
-using any lookups. This will replace the date template `{date:YYYY-MM-dd}`
-with an actual date. This can be confusing in many cases, and it's often both easier and
-more obvious to handle the lookup in code.
-This feature is disabled by default and the message string is logged untouched.
-
-*Note:* Users are *STRONGLY* discouraged from using the lookups option. Doing so may allow uncontrolled user input
-containing lookups to take unintended actions. In almost all cases the software developer can accomplish the same tasks
-lookups perform directly in the application code.
-
-|[[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 the level is the name of the Level
-and value is the value that should be displayed instead of the name of
-the Level.
-
-For example:
-
-....
-%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 gives you the `Error` level name and all other level names of length
-2.
-
-Finally, you can output lower-case level names (the default is upper-case):
-
-....
-%level{lowerCase=true}
-....
-
-|[[PatternRelative]] *r* +
-*relative*
-|Outputs the number of milliseconds elapsed since the JVM was
-started until the creation of the logging event.
-
-|[[PatternRepeat]] *R*\{string}\{count} +
-*repeat*\{string}\{count}
-|Produces a string containing the requested number of instances of the specified string.
-For example, "%repeat{\*}\{2}" will result in the string "**".
-
-|[[PatternReplace]] *replace*\{pattern}\{regex}\{substitution}
-|Replaces occurrences of 'regex', a regular expression, with its
-replacement 'substitution' in the string resulting from the evaluation of
-the pattern. For example, "%replace{%msg}{\s}\{}" will remove all
-spaces contained in the event message.
-
-The pattern can be arbitrarily complex and in particular, can contain
-multiple conversion keywords. For instance, "%replace{%logger
-%msg}{\.}{/}" will replace all dots in the logger or the message of
-the event with a forward slash.
-
-|[[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 the foreground color to black
-
-!Red or FG_Red
-!Set the foreground color to red
-
-!Green or FG_Green
-!Set the foreground color to green
-
-!Yellow or FG_Yellow
-!Set the foreground color to yellow
-
-!Blue or FG_Blue
-!Set the foreground color to blue
-
-!Magenta or FG_Magenta
-!Set the foreground color to magenta
-
-!Cyan or FG_Cyan
-!Set the foreground color to cyan
-
-!White or FG_White
-!Set the foreground color to white
-
-!Default or FG_Default
-!Set the foreground color to default (white)
-
-!BG_Black
-!Set the background color to black
-
-!BG_Red
-!Set the background color to red
-
-!BG_Green
-!Set the background color to green
-
-!BG_Yellow
-!Set the background color to yellow
-
-!BG_Blue
-!Set the background color to blue
-
-!BG_Magenta
-!Set the background color to magenta
-
-!BG_Cyan
-!Set the background color to cyan
+|additionalFields
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[KeyValuePair[\]]
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[`KeyValuePair`] elements denoting additional entries.
+Entry values can contain xref:manual/lookups.adoc[] using `${` syntax.
-!BG_White
-!Set the background color to white
-!===
+|compressionThreshold
+|int
+|Triggers compression if the output is larger than this number of bytes (optional, defaults to 1024)
-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 is 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:../javadoc/log4j-api/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 escape code using the
-JAnsi library. (See link:#enable-jansi[configuration].) Use `\{ansi}` to
-use the default color mapping. You can specify your 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.
-|===
+|compressionType
+|String
+|The compression to use.
+It is optional, and defaults to `GZIP`.
+Accepted values are `GZIP`, `ZLIB`, or `OFF`.
-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.
+|host
+|String
+|The value of the `host` property (optional, defaults to the local host name)
-The optional format modifier is placed between the percent sign and the conversion character.
+|includeMapMessage
+|boolean
+|Whether to include fields from xref:manual/messages.adoc#MapMessage[`MapMessage`]s as additional fields (optional, defaults to `true`)
-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.
+|includeNullDelimiter
+|boolean
+|Whether to include `NULL` byte as delimiter after each event.
+Optional and defaults to `false`.
+Useful for Graylog GELF TCP input.
+Cannot be used with compression.
-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, if 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.
+|includeStacktrace
+|boolean
+|Whether to include full stacktrace of logged ``Throwable``s.
+Optional and defaults to `true`.
+If set to `false`, only the class name and message of the `Throwable` will be included.
-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.
+|includeThreadContext
+|boolean
+|Whether to include thread context as additional fields (optional, defaults to `true`)
-Below are various format modifier examples for the category conversion specifier.
+|mapMessageExcludes
+|String
+|A comma separated list of attributes from the xref:manual/messages.adoc#MapMessage[`MapMessage`] to exclude when formatting the event.
+This attribute only applies when `includeMapMessage` is `true`.
+If `mapMessageIncludes` are also specified, this attribute will be ignored.
-.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 the 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 the 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 the category name is longer than 30
-characters, then truncate from the end.
-|===
+|mapMessageIncludes
+|String
+|A comma separated list of attributes from the xref:manual/messages.adoc#MapMessage[`MapMessage`] to include when formatting the event.
+This attribute only applies when `includeMapMessage` is `true`.
+If `mapMessageExcludes` are also specified, this attribute will override them.
+`MapMessage` fields specified here that have no value will be omitted.
-[#enable-jansi]
-=== ANSI Styling on Windows
+|mapPrefix
+|String
+|A string to prepend to all elements of the xref:manual/messages.adoc#MapMessage[`MapMessage`] when rendered as a field (optional, defaults to an empty string)
-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.
+|[[GELFLayout-messagePattern]] messagePattern
+|String
+|The pattern to use to format the `String`.
+A `messagePattern` and xref:#GELFLayout-patternSelector[`patternSelector`] cannot both be specified.
+If both are present, the message pattern will be ignored and an error will be logged.
+If not supplied, only the text derived from the log message will be used.
+See xref:manual/pattern-layout.adoc[] for information on the pattern strings.
-NOTE: Before 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.
+|omitEmptyFields
+|boolean
+|If `true`, fields which are null or are zero-length strings will not be included as a field in the produced JSON.
+This setting will not affect if those fields appear in the message fields.
+The default value is `false`.
+
+|[[GELFLayout-patternSelector]] patternSelector
+|xref:manual/pattern-layout.adoc#plugin-element-PatternSelector[PatternSelector]
+|The `PatternSelector` to use to format the `String`.
+A xref:#GELFLayout-messagePattern[`messagePattern`] and `patternSelector` cannot both be specified.
+If both are present, the message pattern will be ignored and an error will be logged.
+If not supplied, only the text derived from the logging message will be used.
+See xref:manual/pattern-layout.adoc#plugin-element-PatternSelector[`PatternSelector`] for information on how to specify a `PatternSelector`.
+See xref:manual/pattern-layout.adoc[] for information on the pattern strings.
+
+|threadContextExcludes
+|String
+|A comma separated list of xref:manual/thread-context.adoc[] map keys to exclude when formatting the event.
+This attribute only applies when `includeThreadContext` is `true`.
+If `threadContextIncludes` are also specified, this attribute will be ignored.
-=== Example Patterns
+|threadContextIncludes
+|String
+|A comma separated list of xref:manual/thread-context.adoc[] map keys to include when formatting the event.
+This attribute only applies when `includeThreadContext` is `true`.
+If `threadContextExcludes` are also, specified this attribute will override them.
+Thread context fields specified here that have no value will be omitted.
-==== Filtered Throwables
+|threadContextPrefix
+|String
+|A string to prepend to all elements of the xref:manual/thread-context.adoc[] map when rendered as a field (defaults to an empty string)
+|===
-This example shows how to filter out classes from unimportant packages in stack traces.
+GELF Layout is garbage-free if `compressionType` is `OFF` and there are no additional fields containing `${`.
+.Example configurations
+[%collapsible]
+====
+[tabs]
+=====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.xml[`log4j2.xml`]
[source,xml]
----
-<Configuration>
- <properties>
- <property name="filters">org.junit,org.apache.maven,sun.reflect,java.lang.reflect</property>
- </properties>
- <!-- ... -->
- <PatternLayout pattern="%m%xEx{filters(${filters})}%n"/>
-</Configuration>
+include::example$manual/gelf-layout/log4j2.xml[lines=26..41,indent=0]
----
-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
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/gelf-layout/log4j2.json[lines=5..48,indent=0]
+----
-The log level will be highlighted according to the event's log level.
-All the content that follows the level will be bright green.
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/gelf-layout/log4j2.yaml[lines=21..53,indent=0]
+----
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/gelf-layout/log4j2.properties[`log4j2.properties`]
[source,xml]
----
-<PatternLayout>
- <pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern>
-</PatternLayout>
+include::example$manual/gelf-layout/log4j2.properties[lines=17..48,indent=0]
----
+=====
+<1> Configuration with additional key value pairs
+<2> Configuration for appending to a Graylog server using TCP
+<3> Configuration for appending to a Graylog server using UDP
+====
-[#PatternSelectors]
-=== Pattern Selectors
+[#HTMLLayout]
+=== HTML Layout
-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.
+HTML Layout generates an HTML page, and adds each log event to a row in a table.
+It is configured with the following parameters:
-[#LevelPatternSelector]
-==== LevelPatternSelector
+[%header,cols="1m,1m,4"]
+|===
+|Parameter
+|Type
+|Description
-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.
+|charset
+|String
+|The character encoding
-[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>
-----
+|contentType
+|String
+|The `Content-Type` header value (defaults to `text/html`)
-[#MarkerPatternSelector]
-==== MarkerPatternSelector
+|datePattern
+|String
+|The date format of the log event.
+The default is `JVM_ELAPSE_TIME`, which outputs the milliseconds since JVM started.
+For other valid values, refer to xref:manual/pattern-layout.adoc#converter-date[the `date` conversion specifier of Pattern Layout].
-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.
+|fontName
+|String
+|The `font-family` (defaults to `arial,sans-serif`)
-[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>
-----
+|fontSize
+|String
+|The `font size` (defaults to `small`)
-[#ScriptPatternSelector]
-==== ScriptPatternSelector
+|locationInfo
+|boolean
+|If `true`, the xref:#LocationInformation[source location information] be included (defaults to `false`)
-The ScriptPatternSelector executes a script as described in the
-xref:manual/scripts.adoc[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 Configuration 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.
+|timezone
+|String
+|The time zone ID of the log event.
+If not specified, this layout uses the https://docs.oracle.com/javase/8/docs/api/java/util/TimeZone.html#getDefault()[`TimeZone.getDefault()`] as the default.
+You can use time zone IDs supported by https://docs.oracle.com/javase/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`TimeZone.getTimeZone(String)`].
-[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>
-----
+|title
+|String
+|The HTML page title
+|===
-[#PatternLayout-gcfree]
-=== Garbage-free configuration
+[[JSONLayout]]
+=== JSON Layout
-PatternLayout with the following limited set of conversion patterns is
-garbage-free. Format modifiers to control such things as field width,
-padding, left and right justification will not generate garbage.
+JSON Layout encodes a log event into JSON.
-[cols="1m,2"]
-|===
-|Conversion Pattern |Description
+[WARNING]
+====
+JSON Layout is considered deprecated.
+It is succeeded by xref:#JSONTemplateLayout[] providing more capabilities and efficiency.
+====
-|%c\{precision}, %logger\{precision}
-|Logger name
+.Click for an example output
+[%collapsible]
+====
+[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
+ }
+}
+----
+====
-|%d, %date
-a|
-Note: Only the predefined date formats are garbage-free: (millisecond
-separator may be either a comma ',' or a period '.')
+JSON Layout is configured with the following parameters:
-[cols="1m,1"]
-!===
-!Pattern !Example
+[%header,cols="1m,1m,4"]
+|===
+|Parameter Name
+|Type
+|Description
-!%d\{DEFAULT}
-!2012-11-02 14:34:02,781
+|additionalFields
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[KeyValuePair[\]]
+|link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/KeyValuePair.html[`KeyValuePair`] elements denoting additional entries.
+Entry values can contain xref:manual/lookups.adoc[] using `${` syntax.
-!%d\{ISO8601}
-!2012-11-02T14:34:02,781
+|charset
+|String
+|The character encoding (defaults to `UTF-8`)
-!%d\{ISO8601_BASIC}
-!20121102T143402,781
+|compact
+|boolean
+|If `true`, does not use `endOfLine` and indentation.
+This feature is also referred to as _pretty-printing_ too.
+It defaults to `false`.
-!%d\{ABSOLUTE}
-!14:34:02,781
+|complete
+|boolean
+|
+If `true`, uses `header` and `footer`, and places comma between records – this leads to a well-formed JSON document given `header` and `footer` defaults to `[` and `]`, respectively.
+It defaults to `false`.
-!%d\{DATE}
-!02 Nov 2012 14:34:02,781
+|endOfLine
+|String
+|If set, overrides the default end-of-line string.
+For instance, 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`.
+It is not set by default.
-!%d\{COMPACT}
-!20121102143402781
+|eventEol
+|boolean
+|If `true`, appends an `endOfLine` after each log event, even if `compact=true`.
+It defaults to `false`.
+Use with `eventEol=true` and `compact=true` to get one record per line.
-!%d{HH:mm:ss,SSS}
-!14:34:02,781
+|footer
+|String
+|The footer to include when the stream is closed and `complete=true` (defaults to `]`)
-!%d{dd MMM yyyy HH:mm:ss,SSS}
-!02 Nov 2012 14:34:02,781
+|header
+|String
+|The header to include when the stream is opened and `complete=true` (defaults to `[`)
-!%d{HH:mm:ss}{GMT+0}
-!18:34:02
+|includeNullDelimiter
+|boolean
+|If `true`, a NULL byte will suffix each encoded log event (defaults to `false`)
-!%d\{UNIX}
-!1351866842
+|includeStacktrace
+|boolean
+|If `true`, include full stacktrace of any logged `Throwable` (defaults to `true`)
-!%d\{UNIX_MILLIS}
-!1351866842781
-!===
+|includeTimeMillis
+|boolean
+|If `true`, a `timeMillis` attribute is included in the JSON payload instead of the `instant`.
+`timeMillis` will contain the number of milliseconds since 1970-01-01T00:00:00Z.
-|%enc\{pattern}, %encode\{pattern}
-|Encodes special characters such as
-'\n' and HTML characters to help prevent log forging and some XSS
-attacks that could occur when displaying logs in a web browser -
-garbage-free since 2.8
+|locationInfo
+|boolean
+|If `true`, the appender includes the xref:#LocationInformation[source location information] in the generated JSON (defaults to `false`)
-|%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 - garbage-free since 2.8
+|objectMessageAsJsonObject
+|boolean
+|If `true`, xref:manual/messages.adoc#ObjectMessage[`ObjectMessage`] is serialized as JSON object to the `message` field of the output log (defaults to `false`)
-|%highlight\{pattern}\{style}
-|Adds ANSI colors - garbage-free since 2.7
-(unless nested pattern is not garbage free)
+|properties
+|boolean
+|If `true`, the appender includes the xref:manual/thread-context.adoc[] map in the generated JSON (defaults to `false`)
-|%K\{key}, %map\{key}, %MAP\{key}
-|Outputs the entries in a
-link:../javadoc/log4j-api/org/apache/logging/log4j/message/MapMessage.html[MapMessage],
-if one is present in the event - garbage-free since 2.8.
+|propertiesAsList
+|boolean
+|If `true`, the xref:manual/thread-context.adoc[] map is included as a list of map entry objects, where each entry is denoted as a JSON object containg `key` and `value` fields.
+It defaults to `false`, in which case the thread context map is included as a simple map of key-value pairs.
-|%m, %msg, %message
-|Log message (garbage-free unless message text
-contains '${')
+|stacktraceAsString
+|boolean
+|If `true`, the stacktrace will be formatted as `String`, and not a nested object (optional, defaults to `false`)
+|===
-|%marker
-|The full name of the marker (including parents) - garbage-free
-since 2.8
+Additional runtime dependencies are required for using JSON Layout:
-|%markerSimpleName
-|The simple name of the marker (not including
-parents)
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<dependency>
+ <groupId>com.fasterxml.jackson.core</groupId>
+ <artifactId>jackson-databind</artifactId>
+ <version>{jackson-version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
-|%maxLen, %maxLength
-|Truncates another pattern to some max number of
-characters - garbage-free since 2.8
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:{jackson-version}'
+----
+====
-|%n
-|The platform dependent line separator
+[#JSONTemplateLayout]
+=== JSON Template Layout
-|%N, %nano
-|System.nanoTime() when the event was logged
+JSON Template Layout is a customizable, efficient, and garbage-free JSON generating layout.
+It encodes ``LogEvent``s according to the structure described by the JSON template provided.
+For instance, given the following event template stored in `MyLayout.json` in your classpath:
-|%notEmpty\{pattern}, %varsNotEmpty\{pattern},
-%variablesNotEmpty\{pattern}
-|Outputs the result of evaluating the
-pattern if and only if all variables in the pattern are not empty -
-garbage-free since 2.8
+[source,json]
+----
+{
+ "instant": { // <1>
+ "$resolver": "timestamp",
+ "pattern": {
+ "format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
+ "timeZone": "UTC"
+ }
+ },
+ "someConstant": 1, // <2>
+ "message": { // <3>
+ "$resolver": "message",
+ "stringified": true
+ }
+}
+----
+<1> Using the `timestamp` event template resolver to populate the `instant` field
+<2> Passing a constant that will be rendered as is
+<3> Using the `message` event template resolver to populate the `message` field
-|%p, %level
-|The level of the logging event
+in combination with the below layout configuration:
-|%r, %relative
-|The number of milliseconds elapsed since the JVM was
-started until the creation of the logging event - garbage-free since 2.8
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
-|%sn, %sequenceNumber
-|A sequence number that will be incremented in
-every event - garbage-free since 2.8
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/json-template-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
-|%style\{pattern}{ANSI style}
-|Style the message - garbage-free since
-2.7 (unless nested pattern is not garbage free)
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
-|%T, %tid, %threadId
-|The ID of the thread that generated the logging
-event
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
-|%t, %tn, %thread, %threadName
-|The name of the thread that generated
-the logging event
+JSON Template Layout generates JSON as follows:
-|%tp
-|The priority of the thread that generated the logging event
+[source,json]
+----
+{"instant":"2017-05-25T19:56:23.370Z","someConstant":1,"message":"Hello, error!"} //<1>
+----
+<1> JSON pretty-printing is not supported for performance reasons.
-|%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 -
-garbage-free since 2.8
+Good news is JSON Template Layout is perfectly production-ready without any configuration!
+It bundles several predefined event templates modeling popular JSON-based log formats.
-|literal text
-|Garbage-free unless literal contains '${' (variable
-substitution)
-|===
+Read more on xref:manual/json-template-layout.adoc[]...
-Other PatternLayout conversion patterns, and other Layouts may be
-updated to avoid creating temporary objects in future releases. (Patches
-welcome!)
+[id=pattern-layout]
+=== [[PatternLayout]] Pattern Layout
-NOTE: Logging exceptions and stack traces will create temporary
-objects with any layout. (However, Layouts will only create these
-temporary objects when an exception actually occurs.) We haven't figured
-out a way to log exceptions and stack traces without creating temporary
-objects. That is unfortunate, but you probably still want to log them
-when they happen.
+Pattern Layout is a customizable, efficient, garbage-free, and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
-[NOTE]
+[IMPORTANT]
====
-patterns containing regular expressions and lookups for property
-substitution will result in temporary objects being created during
-steady-state logging.
-
-Including location information is done by walking the stacktrace of an
-exception, which creates temporary objects, so the following patterns
-are not garbage-free:
-
-* %C, %class - Class Name
-* %F, %file - File Location
-* %l, %location - Location
-* %L, %line - Line Location
-* %M, %method - Method Location
-
-Also, the pattern converters for formatting Throwables are not
-garbage-free:
-
-* %ex, %exception, %throwable - The Throwable trace bound to the
-LoggingEvent
-* %rEx, %rException %rThrowable - Same as %ex but with wrapping
-exceptions
-* %xEx, %xException, %xThrowable - Same as %ex but with class packaging
-information
-* %u, %uuid - Creates a new random or time-based UUID while formatting
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
====
-[#PatternLayout-performance]
-=== Performance
+A conversion pattern is composed of literal text and format control expressions.
+For instance, given the `%-5p [%t]: %m%n` pattern, following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
-Great effort has been put into the efficiency of Pattern Layout.
-To get the most out of it, mind the following checklist:
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
-* Enable xref:manual/garbagefree.adoc[garbage-free logging]
-* Mind xref:#PatternLayout-gcfree[the garbage footprint of features you use]
-* Don't give too much slack to xref:manual/systemproperties.adoc#log4j2.layoutStringBuilderMaxSize[`log4j2
-.layoutStringBuilderMaxSize`] and try to keep it relatively tight
+Read more on xref:manual/pattern-layout.adoc[]...
[#RFC5424Layout]
-== RFC5424 Layout
+=== RFC 5424 Layout
+
+RFC 5424 Layout encodes log events according to https://datatracker.ietf.org/doc/html/rfc5424#section-6[the Syslog message format described in RFC 5424].
-As the name implies, the Rfc5424Layout formats LogEvents by 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.
+[NOTE]
+====
+RFC 5424 obsoletes RFC 3164, implemented by xref:#SyslogLayout[].
+====
+
+RFC 5424 Layout is configured with the following parameters:
-.Rfc5424Layout Parameters
-[cols="1m,1,4"]
+[%header,cols="1m,1m,4"]
|===
-|Parameter Name |Type |Description
+|Parameter
+|Type
+|Description
|appName
|String
-|The value to use as the APP-NAME in the RFC 5424
-syslog record.
+|The `APP-NAME` field as described in RFC 5424
|charset
|String
-|The character set to use when converting the syslog
-String to a byte array. The String must be 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.
+|The character encoding (defaults to `UTF-8`)
|enterpriseNumber
|integer
-|The IANA enterprise number as described in
-http://tools.ietf.org/html/rfc5424#section-7.2.2[RFC 5424]
+|The `enterpriseId` parameter as described in RFC 5424 (defaults to `32473`)
Review Comment:
```suggestion
|
The `enterpriseId` parameter as described in RFC 5424.
If missing `32473` will be used, which is
https://www.rfc-editor.org/rfc/rfc5612.html#section-2[reserved for documentation use].
```
##########
src/site/antora/modules/ROOT/pages/manual/layouts.adoc:
##########
@@ -14,2120 +14,863 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-= Layouts
-An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be consuming the log event.
-In Log4j 1.x and Logback Layouts were expected to transform an event into a String.
-In Log4j 2 Layouts return a byte array.
-This allows the result of the Layout to be useful in many more types of Appenders.
-However, this means you need to configure most Layouts with a
-https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[`Charset`]
-to ensure the byte array contains correct values.
+= Layouts
-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.
+An xref:manual/appenders.adoc[appender] uses a *layout* to encode a link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[`LogEvent`] into a form that meets the needs of whatever will be consuming the log event.
+This page will try to answer following questions:
-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.
+* xref:#concerns[What are some common concerns shared by all predefined layouts?]
+* xref:#collection[Which layouts does Log4j provide?]
+* xref:#extending[How can you create custom layouts?]
-[#common-concerns]
+[#concerns]
== Common concerns
+This section introduces you to some common concerns shared by almost all xref:#collection[predefined layouts] that you need to be aware of while using them.
+
+[#charset]
+=== Character encoding
+
+All xref:#collection[predefined layouts] produce `String` that eventually get converted into a `byte[]` using the https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html[`Charset`] configured.
+While doing so, they use `UTF-8` by default.
+If you want all your log events to be formatted in a certain character encoding that is different than what the employed layout defaults to, make sure to configure the layout's character encoding as needed.
+
[#LocationInformation]
=== Location information
include::partial$manual/layouts-location-information.adoc[]
-[#CSVLayouts]
-== CSV Layouts
+[#collection]
+== Collection
+
+Log4j bundles predefined layouts to assist in several common deployment use cases.
+Let's start with shortcuts to most used ones:
+
+* Are you looking for a production-grade *JSON layout ready to be deployed to a log ingestion system* such as Elasticsearch or Google Cloud?
+Refer to xref:manual/json-template-layout.adoc[].
-As of Log4j 2.11.0, CSV support has moved from the existing module
-`log4j-core` to the new module `log4j-csv`.
+* Are you looking for a layout that encodes log events in a *human-readable format suitable for tests and local development*?
+Refer to xref:manual/pattern-layout.adoc[].
-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.
+Following sections explain all predefined layouts in detail.
-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.
+[#csv-layouts]
+=== [[CSVLayouts]] CSV Layouts
-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:
+There are two layouts performing https://en.wikipedia.org/wiki/Comma-separated_values[Comma Separated Value (CSV)] encoding:
+
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/CsvParameterLayout.html[`CsvParameterLayout`]::
+It encodes *only* the parameters of the message of a log event.
+Generated CSV records will be composed of fields denoting the message parameters.
++
+.Click here for examples
+[%collapsible]
+====
+Given the following statement
[source,java]
----
-logger.info("Ignored", value1, value2, value3);
+LOGGER.info("Record1 {} {}", "arg1", "arg2");
+LOGGER.error("Record2 {} {} {}", "arg3", "arg4", "arg5", throwable);
----
-Which will create the CSV record:
+`CsvParameterLayout` will output
-....
-value1, value2, value3
-....
+[source,text]
+----
+arg1,arg2
+arg3,arg4,arg5
+----
+
+The same can be achieved using link:../javadoc/log4j-api/org/apache/logging/log4j/message/ObjectArrayMessage.html[`ObjectArrayMessage`] as follows:
+
+[source,java]
+----
+LOGGER.info(new ObjectArrayMessage("arg1", "arg2"));
+LOGGER.info(new ObjectArrayMessage("arg3", "arg4", "arg5"));
+----
+====
-Alternatively, you can use an `ObjectArrayMessage`, which only carries parameters:
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/CsvLogEventLayout.html[`CsvLogEventLayout`]::
+It encodes the complete log event, including the formatted message.
+Generated CSV records will be composed of following fields in the given order:
++
+. Time (in nanoseconds)
+. Time (in milliseconds)
+. Level
+. Thread ID
+. Thread name
+. Thread priority
+. Message (formatted, hence including parameters)
+. Logger FQCN
+. Logger name
+. Marker
+. Throwable
+. Source
+. Thread context map
+. Thread context stack
+
++
+.Click here for examples
+[%collapsible]
+====
+Given the following statement
[source,java]
----
-logger.info(new ObjectArrayMessage(value1, value2, value3));
+LOGGER.debug("one={}, two={}, three={}", 1, 2, 3);
+----
+
+`CsvLogEventLayout` will output
+
+[source,text]
+----
+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),{},[]
----
+====
-The layouts `CsvParameterLayout` and `CsvLogEventLayout` are configured with the following parameters:
+Both `CsvParameterLayout` and `CsvLogEventLayout` are configured with the following parameters:
-.CsvParameterLayout and CsvLogEventLayout
-[cols="1m,1,4"]
+[%header,cols="1m,1m,4"]
|===
-|Parameter Name |Type |Description
+|Parameter
+|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].
+|A predefined format name (`Default`, `Excel`, `MySQL`, `RFC4180`, `TDF`, etc.) accepted by https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html[`CSVFormat`]
|delimiter
|Character
-|Sets the delimiter of the format to the specified character.
+|The field delimiter character
|escape
|Character
-|Sets the escape character of the format to the specified character.
+|The escape character
|quote
|Character
-|Sets the quoteChar of the format to the specified
-character.
+|The quote character
|quoteMode
|String
-|Sets the output quote policy of the format to the
-specified value. One of: `ALL`, `MINIMAL`, `NON_NUMERIC`, `NONE`.
+|A quote mode name (`ALL`, `ALL_NONE_NULL`, `MINIMAL`, `NON_NUMERIC`, `NONE`, etc.) accepted by https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/QuoteMode.html[`QuoteMode`]
|nullString
|String
-|Writes null as the given nullString when writing records.
+|The string to denote `null` values
|recordSeparator
|String
-|Sets the record separator of the format to the specified String.
+|The record separator string
|charset
|Charset
-|The output Charset.
+|The character encoding
|header
-|Sets the header to include when the stream is opened.
-|Desc.
+|String
+|The header to include when the stream is opened
|footer
-|Sets the footer to include when the stream is closed.
-|Desc.
+|String
+|The footer to include when the stream is closed
|===
-Logging as a CSV event 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 runtime dependencies are required for using CSV layouts
-[%collapsible,id=log4j-csv-deps]
-=====
-include::partial$manual/dependencies-log4j-csv.adoc[]
-=====
-
-[#GELFLayout]
-== GELF Layout
-
-Encodes log events in https://go2docs.graylog.org/current/getting_in_log_data/gelf.html#GELFPayloadSpecification[the GELF specification] version `1.1`.
-Compresses JSON to GZIP or ZLIB (`compressionType`) if log event data is larger than 1024 bytes (`compressionThreshold`).
-This layout does not implement chunking.
+There are additional runtime dependencies are required for using CSV layouts:
Review Comment:
```suggestion
Additional runtime dependencies are required for using CSV layouts:
```
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, exceptions are always written even if the pattern contains no exception conversions.
Review Comment:
```suggestion
If `true` and the user-provided pattern does not contain an exception converter, an implicit xref:#converter-exception-extended[`%xEX`] pattern is appended.
```
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
Review Comment:
```suggestion
`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
[WARNING]
====
If the provided pattern does not contain an exception converter and <<plugin-attr-alwaysWriteExceptions>> is not disabled, an implicit xref:#converter-exception-extended[`%xEX`] is appended to the pattern.
====
```
##########
src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc:
##########
@@ -16,422 +16,479 @@
////
= JSON Template Layout
-`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON
-generating layout. It encodes ``LogEvent``s according to the structure described
-by the JSON template provided. In a nutshell, it shines with its
+JSON Template Layout is a customizable, xref:#performance[efficient], and xref:#faq-garbage-free[garbage-free] JSON generating layout.
+It encodes ``LogEvent``s according to the structure described by the JSON template provided.
+In a nutshell, it shines with its
-* Customizable JSON structure (see `eventTemplate[Uri]` and
- `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration] parameters)
+* Customizable JSON structure (see `eventTemplate[Uri]` and `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration] parameters)
-* Customizable timestamp formatting (see xref:#event-template-resolver-timestamp[]
- event template resolver)
+* Customizable timestamp formatting (see xref:#event-template-resolver-timestamp[] event template resolver)
-* Feature rich exception formatting (see xref:#event-template-resolver-exception[]
- and xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
+* Feature rich exception formatting (see xref:#event-template-resolver-exception[] and xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
* xref:manual/extending.adoc[Extensible plugin support]
* Customizable object xref:#recycling-strategy[recycling strategy]
+[TIP]
+====
+JSON Template Layout is intended for production deployments where the generated logs are expected to be delivered to an external log ingestion system such as Elasticsearch or Google Cloud Logging.
+While running tests or developing locally, you can use xref:manual/pattern-layout.adoc[] for human-readable log output.
+====
+
[#usage]
== Usage
-Adding `log4j-layout-template-json` artifact to your list of dependencies is
-enough to enable access to `JsonTemplateLayout` in your Log4j configuration:
+Adding `log4j-layout-template-json` artifact to your list of dependencies is enough to enable access to JSON Template Layout in your Log4j configuration:
+[tabs]
+====
+Maven::
++
[source,xml,subs="+attributes"]
----
-<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-layout-template-json</artifactId>
- <version>{log4j-layout-template-json-version}</version>
-</dependency>
+<project>
+
+ <!-- Assuming `log4j-bom` is imported --><!--1-->
+
+ <dependency>
+
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-layout-template-json</artifactId>
+ <scope>runtime</scope><!--2-->
+ </dependency>
+
+ </dependency>
+
+</project>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
----
+dependencies {
+
+ // Assuming `log4j-bom` is imported <1>
-For instance, given the following JSON template modelling
-https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification]
-(accessible via `classpath:EcsLayout.json`)
+ runtimeOnly // <2>
+ 'org.apache.logging.log4j:log4j-slf4j2-impl'
+
+}
+----
+====
+<1> Assuming you xref:manual/installation.adoc#bom[imported `org.apache.logging.log4j:log4j-bom`]
+<2> For applications, logging implementation dependencies are required at _runtime_.
+If you want to use JSON Template Layout for tests, you need to switch the scope to _test_.
+See xref:manual/installation.adoc[] for details.
+
+JSON Template Layout is primarily configured through an *event template* describing the structure log events should be JSON-encoded in.
+Event templates themselves are also JSON documents, where objects containing `$resolver` members, such as,
+
+[source,json]
+----
+{
+ "$resolver": "message", // <1>
+ "stringified": true // <2>
+}
+----
+<1> Indicating that this object should be replaced with the output from the xref:#event-template-resolver-message[`message` *event template resolver*]
+<2> Passing a configuration to the `message` event template resolver
+
+are interpreted by the JSON Template Layout compiler, and replaced with the referenced event or stack trace *template resolver* rendering that particular item.
+
+For instance, given the following event template stored in `MyLayout.json` in your classpath:
[source,json]
----
{
- "@timestamp": {
+ "instant": { // <1>
"$resolver": "timestamp",
"pattern": {
"format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
"timeZone": "UTC"
}
},
- "ecs.version": "1.2.0",
- "log.level": {
- "$resolver": "level",
- "field": "name"
- },
- "message": {
+ "someConstant": 1, // <2>
+ "message": { // <3>
"$resolver": "message",
"stringified": true
- },
- "process.thread.name": {
- "$resolver": "thread",
- "field": "name"
- },
- "log.logger": {
- "$resolver": "logger",
- "field": "name"
- },
- "labels": {
- "$resolver": "mdc",
- "flatten": true,
- "stringified": true
- },
- "tags": {
- "$resolver": "ndc"
- },
- "error.type": {
- "$resolver": "exception",
- "field": "className"
- },
- "error.message": {
- "$resolver": "exception",
- "field": "message"
- },
- "error.stack_trace": {
- "$resolver": "exception",
- "field": "stackTrace",
- "stackTrace": {
- "stringified": true
- }
}
}
----
+<1> Using xref:#event-template-resolver-timestamp[the `timestamp` event template resolver] to populate the `instant` field
+<2> Passing a constant that will be rendered as is
+<3> Using xref:#event-template-resolver-message[the `message` event template resolver] to populate the `message` field
-in combination with the below `log4j2.xml` configuration:
+in combination with the below layout configuration:
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.xml[`log4j2.xml`]
[source,xml]
----
-<JsonTemplateLayout eventTemplateUri="classpath:EcsLayout.json"/>
+include::example$manual/json-template-layout/usage/log4j2.xml[lines=26..26,indent=0]
----
-or with the below `log4j2.properties` configuration:
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/json-template-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
-[source,properties]
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
----
-appender.console.layout.type = JsonTemplateLayout
-appender.console.layout.eventTemplateUri = classpath:EcsLayout.json
+include::example$manual/json-template-layout/usage/log4j2.yaml[lines=22..23,indent=0]
----
-`JsonTemplateLayout` generates JSON as follows:
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+JSON Template Layout generates JSON as follows:
[source,json]
----
-{
- "@timestamp": "2017-05-25T19:56:23.370Z",
- "ecs.version": "1.2.0",
- "log.level": "ERROR",
- "message": "Hello, error!",
- "process.thread.name": "main",
- "log.logger": "org.apache.logging.log4j.JsonTemplateLayoutDemo",
- "error.type": "java.lang.RuntimeException",
- "error.message": "test",
- "error.stack_trace": "java.lang.RuntimeException: test\n\tat org.apache.logging.log4j.JsonTemplateLayoutDemo.main(JsonTemplateLayoutDemo.java:11)\n"
-}
+{"instant":"2017-05-25T19:56:23.370Z","someConstant":1,"message":"Hello, error!"} //<1>
----
+<1> JSON pretty-printing is not supported for performance reasons.
+
+Good news is *JSON Template Layout is perfectly production-ready without any configuration!*
+The event template defaults to `EcsLayout.json`, bundled in the classpath, modelling https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification].
+JSON Template Layout bundles several more xref:#event-templates[predefined event templates] modeling popular JSON-based log formats.
-[#layout-config]
-== Layout Configuration
+[#config]
+== Configuration
-`JsonTemplateLayout` is configured with the following parameters:
+This section explains how to configure JSON Template Layout plugin element in a Log4j configuration file.
-.`JsonTemplateLayout` parameters
-[cols="1m,1m,4"]
+[TIP]
+====
+Are you trying to implement your own event (or stack trace) template and looking for help on available resolvers?
+Please refer to xref:#template-config[] instead.
+====
+
+[#plugin-attrs]
+=== Plugin attributes
+
+JSON Template Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
|===
-| Parameter Name
-| Type
-| Description
-
-| charset
-| Charset
-| `Charset` used for `String` encoding
-
-| [[locationInfoEnabled]]locationInfoEnabled
-| boolean
-| toggles access to the `LogEvent` source; file name, line number, etc.
- (defaults to `false` set by `log4j.layout.jsonTemplate.locationInfoEnabled`
- property)
-
-| stackTraceEnabled
-| boolean
-| toggles access to the stack traces (defaults to `true` set by
- `log4j.layout.jsonTemplate.stackTraceEnabled` property)
-
-| eventTemplate
-| String
-| inline JSON template for rendering ``LogEvent``s (has priority over
- `eventTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplate` property)
-
-| eventTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``LogEvent``s (defaults to
- `classpath:EcsLayout.json` set by `log4j.layout.jsonTemplate.eventTemplateUri`
- property)
-
-| eventTemplateRootObjectKey
-| String
-| if present, the event template is put into a JSON object composed of a single
- member with the provided key (defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplateRootObjectKey`
- property)
-
-| eventTemplateAdditionalField
-| EventTemplateAdditionalField[]
-| additional key-value pairs appended to the root of the event template
-
-| stackTraceElementTemplate
-| String
-| inline JSON template for rendering ``StackTraceElement``s (has priority over
- `stackTraceElementTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplate` property)
-
-| stackTraceElementTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``StackTraceElement``s
- (defaults to `classpath:StackTraceElementLayout.json` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplateUri` property)
-
-| eventDelimiter
-| String
-| delimiter used for separating rendered ``LogEvent``s (defaults to
- `System.lineSeparator()` set by `log4j.layout.jsonTemplate.eventDelimiter`
- property)
-
-| nullEventDelimiterEnabled
-| boolean
-| append `\0` (`null`) character to the end of every `eventDelimiter`
- separating rendered ``LogEvent``s (defaults to `false` set by
- `log4j.layout.jsonTemplate.nullEventDelimiterEnabled` property)
-
-| [[maxStringLength]] maxStringLength
-| int
-| truncate string values longer than the specified limit (defaults to 16384 set
- by `log4j.layout.jsonTemplate.maxStringLength` property)
-
-| truncatedStringSuffix
-| String
-| suffix to append to strings truncated due to exceeding `maxStringLength`
- (defaults to `…` set by `log4j.layout.jsonTemplate.truncatedStringSuffix`
- property)
-
-| recyclerFactory
-| RecyclerFactory
-| recycling strategy that can either be `dummy`, `threadLocal`, or `queue`
- (set by `log4j.layout.jsonTemplate.recyclerFactory` property)
+|Type |`Charset`
+|Default value |`UTF-8`
+|Configuration property |`log4j.layout.jsonTemplate.charset`
|===
-[#additional-event-template-fields]
-=== Additional event template fields
+`Charset` used for encoding the produced JSON into bytes
Review Comment:
Unless I am wrong JSON **must** be encoded in `UTF-8`. Should we add a note to users?
##########
src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc:
##########
@@ -1983,10 +2046,10 @@ To get the most out of it, mind the following checklist:
[#faq-lookups]
=== Are lookups supported in templates?
-Yes, xref:manual/lookups.adoc[lookups] (e.g., `${java:version}`,
-`${env:USER}`, `${date:MM-dd-yyyy}`) are supported in string
-literals of templates. Though note that they are not garbage-free.
+Yes, xref:manual/lookups.adoc[lookups] (e.g., `${java:version}`, `${env:USER}`, `${date:MM-dd-yyyy}`) are supported in string literals of templates.
+Though note that they are not garbage-free.
Review Comment:
Should we point to the rules in `manual/configuration.adoc#lazy-property-substitution`?
Unless I am mistaken:
- an external template file is not interpolated at configuration time, so `$` does not need to be escaped,
- an inline template or `EventTemplateAdditionalField` **are** interpolated and `$`s need to be escaped as `$$`,
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
Review Comment:
I find this (legacy) description confusing.
I tried to provide a better one in [this SO answer](https://stackoverflow.com/a/76410279/11748454).
We have tons of `%c` examples, but we lack the newly added `1.n*` abbreviator that abbreviates each component to a single letter, except the `n` rightmost components.
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%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
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+You can enable xref:manual/lookups.adoc[] using `\{lookups}` and log messages like `${date:YYYY-MM-dd}` using lookups.
Review Comment:
Can you really evaluate _lookups_ in **messages**?
I think this functionality was removed around `2.17.x`.
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
Review Comment:
The `style` attribute is by far the most complex one.
Its syntax is a comma-separated list of specifiers in the form:
- `DISABLEANSI`, `NOCONSOLENOANSI`: we might want to mention that these specifiers are accepted for BC, but redirect users to the `disableAnsi` and `noConsoleNoAnsi` configuration attributes of `PatternLayout`.
- `STYLE=(DEFAULT|LOGBACK)`: is replaced by a predefined map level->color specifier. This **should** appear first in the list.
- `<level_name>=<color_specifier>`: the `<color_specifier>` part is again a complex structure. We should consider creating a separate section on how to specify colors, since the logic is shared with `%style`.
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%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
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+You can enable xref:manual/lookups.adoc[] using `\{lookups}` and log messages like `${date:YYYY-MM-dd}` using lookups.
+This will replace the date template `YYYY-MM-dd` with an actual date.
+This can be confusing in many cases, and it's often both easier and more obvious to handle the lookup in code.
+This feature is disabled by default and the message string is logged untouched.
+
+[WARNING]
+====
+Users are strongly discouraged from using the lookups option.
+Doing so may allow uncontrolled user input containing lookups to take unintended actions.
+====
+
+[#converter-method]
+==== Method
+
+Outputs the method name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MethodLocationPatternConverter.html[`MethodLocationPatternConverter`] specifier grammar
+[source,text]
+----
+M
+method
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the method name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-nano]
+==== Nanoseconds
+
+Outputs the result of `System.nanoTime()` at the time the log event was created
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NanoTimePatternConverter.html[`NanoTimePatternConverter`] specifier grammar
+[source,text]
+----
+N
+nano
+----
+
+[#converter-not-empty]
+==== Not empty
+
+Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/VariablesNotEmptyReplacementConverter.html[`VariablesNotEmptyReplacementConverter`] specifier grammar
+[source,text]
+----
+variablesNotEmpty{pattern}
+varsNotEmpty{pattern}
+notEmpty{pattern}
+----
+
+For example:
+
+[source,text]
+----
+%notEmpty{[%marker]}
+----
+
+[#converter-pid]
+==== Process ID
+
+Outputs the process ID, if supported by the underlying platform
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ProcessIdPatternConverter.html[`ProcessIdPatternConverter`] specifier grammar
+[source,text]
+----
+pid{defaultValue}
+processId{defaultValue}
+----
+
+An optional `defaultValue` may be specified to be shown, if the platform does not support process IDs.
+
+[#converter-relative]
+==== Relative
+
+Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RelativeTimePatternConverter.html[`RelativeTimePatternConverter`] specifier grammar
+[source,text]
+----
+r
+relative
+----
+
+[#converter-repeat]
+==== Repeat
+
+Produces a string containing the requested number of instances of the specified string
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RepeatPatternConverter.html[`RepeatPatternConverter`] specifier grammar
+[source,text]
+----
+R{string}{count}
+repeat{string}{count}
+----
+
+For example, `%repeat{\*}\{2}` will result in the string `**`.
+
+[#converter-replace]
+==== Replace
+
+Replaces occurrences of a regular expression (`regex`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RegexReplacementConverter.html[`RegexReplacementConverter`] specifier grammar
+[source,text]
+----
+replace{pattern}{regex}{substitution}
+----
+
+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.
+
+[#converter-rootException]
+==== Root exception
+
+The same as xref:#converter-exception[the `exception` converter], but the stack trace is printed starting with the first exception in the causal chain that was thrown followed by each subsequent wrapping exception
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.html[`RootThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+rEx|rException|rThrowable
+ {
+ ["none" | "short" | "full" | depth]
+ [,filters(package,package,...)]
+ [,separator(separator)]
+ }
+ {ansi(
+ Key=Value,Value,...
+ Key=Value,Value,...
+ ...)
+ }
+ {suffix(pattern)}
+----
+
+The throwable conversion specifier can be followed by an option in the form `%rEx\{short}`, which will only output the first line of the `Throwable`, or `%rEx\{n}`, where the first `n` lines of the stack trace will be printed.
+
+Specifying `%rEx\{none}` or `%rEx\{0}` will suppress printing of the exception.
+
+Use `filters(packages)`, where `packages` is a list of package names to suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace, e.g., `separator(|)`.
+The default value is the `line.separator` system property, which is platform dependent.
+
+Use `rEx{suffix(pattern)}` to add the output of `pattern` to the output only when there is a `Throwable` to print.
+
+[#converter-seq]
+==== Sequence number
+
+Includes a sequence number that will be incremented in every event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/SequenceNumberPatternConverter.html[`SequenceNumberPatternConverter`] specifier grammar
+[source,text]
+----
+sn
+sequenceNumber
+----
+
+The counter is a static variable, so will only be unique within applications that share the same converter class object.
+
+[#converter-style]
+==== Style
+
+Use ANSI escape sequences to style the result of the enclosed pattern.
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/StyleConverter.html[`StyleConverter`] specifier grammar
+[source,text]
+----
+style{pattern}{ANSI style}
+----
+
+The style can consist of a comma-separated list of style names from the following table:
Review Comment:
For compatibility with `%highlight` this can also be a space-separated list.
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%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
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+You can enable xref:manual/lookups.adoc[] using `\{lookups}` and log messages like `${date:YYYY-MM-dd}` using lookups.
+This will replace the date template `YYYY-MM-dd` with an actual date.
+This can be confusing in many cases, and it's often both easier and more obvious to handle the lookup in code.
+This feature is disabled by default and the message string is logged untouched.
+
+[WARNING]
+====
+Users are strongly discouraged from using the lookups option.
+Doing so may allow uncontrolled user input containing lookups to take unintended actions.
+====
+
+[#converter-method]
+==== Method
+
+Outputs the method name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MethodLocationPatternConverter.html[`MethodLocationPatternConverter`] specifier grammar
+[source,text]
+----
+M
+method
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the method name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-nano]
+==== Nanoseconds
+
+Outputs the result of `System.nanoTime()` at the time the log event was created
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NanoTimePatternConverter.html[`NanoTimePatternConverter`] specifier grammar
+[source,text]
+----
+N
+nano
+----
+
+[#converter-not-empty]
+==== Not empty
+
+Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/VariablesNotEmptyReplacementConverter.html[`VariablesNotEmptyReplacementConverter`] specifier grammar
+[source,text]
+----
+variablesNotEmpty{pattern}
+varsNotEmpty{pattern}
+notEmpty{pattern}
+----
+
+For example:
+
+[source,text]
+----
+%notEmpty{[%marker]}
+----
+
+[#converter-pid]
+==== Process ID
+
+Outputs the process ID, if supported by the underlying platform
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ProcessIdPatternConverter.html[`ProcessIdPatternConverter`] specifier grammar
+[source,text]
+----
+pid{defaultValue}
+processId{defaultValue}
+----
+
+An optional `defaultValue` may be specified to be shown, if the platform does not support process IDs.
+
+[#converter-relative]
+==== Relative
+
+Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RelativeTimePatternConverter.html[`RelativeTimePatternConverter`] specifier grammar
+[source,text]
+----
+r
+relative
+----
+
+[#converter-repeat]
+==== Repeat
+
+Produces a string containing the requested number of instances of the specified string
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RepeatPatternConverter.html[`RepeatPatternConverter`] specifier grammar
+[source,text]
+----
+R{string}{count}
+repeat{string}{count}
+----
+
+For example, `%repeat{\*}\{2}` will result in the string `**`.
+
+[#converter-replace]
+==== Replace
+
+Replaces occurrences of a regular expression (`regex`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RegexReplacementConverter.html[`RegexReplacementConverter`] specifier grammar
+[source,text]
+----
+replace{pattern}{regex}{substitution}
+----
+
+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.
+
+[#converter-rootException]
+==== Root exception
+
+The same as xref:#converter-exception[the `exception` converter], but the stack trace is printed starting with the first exception in the causal chain that was thrown followed by each subsequent wrapping exception
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.html[`RootThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+rEx|rException|rThrowable
+ {
+ ["none" | "short" | "full" | depth]
+ [,filters(package,package,...)]
+ [,separator(separator)]
+ }
+ {ansi(
+ Key=Value,Value,...
+ Key=Value,Value,...
+ ...)
+ }
+ {suffix(pattern)}
+----
+
+The throwable conversion specifier can be followed by an option in the form `%rEx\{short}`, which will only output the first line of the `Throwable`, or `%rEx\{n}`, where the first `n` lines of the stack trace will be printed.
+
+Specifying `%rEx\{none}` or `%rEx\{0}` will suppress printing of the exception.
+
+Use `filters(packages)`, where `packages` is a list of package names to suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace, e.g., `separator(|)`.
+The default value is the `line.separator` system property, which is platform dependent.
+
+Use `rEx{suffix(pattern)}` to add the output of `pattern` to the output only when there is a `Throwable` to print.
+
+[#converter-seq]
+==== Sequence number
+
+Includes a sequence number that will be incremented in every event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/SequenceNumberPatternConverter.html[`SequenceNumberPatternConverter`] specifier grammar
+[source,text]
+----
+sn
+sequenceNumber
+----
+
+The counter is a static variable, so will only be unique within applications that share the same converter class object.
+
+[#converter-style]
+==== Style
+
+Use ANSI escape sequences to style the result of the enclosed pattern.
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/StyleConverter.html[`StyleConverter`] specifier grammar
+[source,text]
+----
+style{pattern}{ANSI style}
+----
+
+The style can consist of a comma-separated list of style names from the following table:
+
+[%header,cols="2m,3"]
+|===
+|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 the foreground color to black
+
+|Red or FG_Red
+|Set the foreground color to red
+
+|Green or FG_Green
+|Set the foreground color to green
+
+|Yellow or FG_Yellow
+|Set the foreground color to yellow
+
+|Blue or FG_Blue
+|Set the foreground color to blue
+
+|Magenta or FG_Magenta
+|Set the foreground color to magenta
+
+|Cyan or FG_Cyan
+|Set the foreground color to cyan
+
+|White or FG_White
+|Set the foreground color to white
+
+|Default or FG_Default
+|Set the foreground color to default (white)
+
+|BG_Black
+|Set the background color to black
+
+|BG_Red
+|Set the background color to red
+
+|BG_Green
+|Set the background color to green
+
+|BG_Yellow
+|Set the background color to yellow
+
+|BG_Blue
+|Set the background color to blue
+
+|BG_Magenta
+|Set the background color to magenta
+
+|BG_Cyan
+|Set the background color to cyan
+
+|BG_White
+|Set the background color to white
+|===
+
+For example:
+
+[source,text]
+----
+%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}
+----
+
+You can also combine styles:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}
+----
+
+[#converter-thread-context-stack]
+==== Thread context stack
+
+Outputs the xref:manual/thread-context.adoc[] stack (aka. Nested Diagnostic Context or NDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NdcPatternConverter.html[`NdcPatternConverter`] specifiers grammar
+[source,text]
+----
+x
+NDC
+----
+
+[#converter-thread-context-map]
+==== Thread context map
+
+Outputs the xref:manual/thread-context.adoc[] map (aka. Mapped Diagnostic Context or MDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MdcPatternConverter.html[`MdcPatternConverter`] specifiers grammar
+[source,text]
+----
+X{key[,key2...]}
+mdc{key[,key2...]}
+MDC{key[,key2...]}
+----
+
+The *X* conversion character can be followed by one or more keys for the map placed between braces, as in `%X\{clientNumber}`, where `clientNumber` is the key.
+The value in the MDC corresponding to the key will be output.
+
+If a list of keys is provided, such as `%X{name, number}`, then each key that is present in the thread context will be output using the format `{name=val1, number=val2}`.
+The key/value pairs will be printed in the order they appear in the list.
+
+If no sub-options are specified then the entire contents of the MDC key-value pair set is output using a format `{key1=val1, key2=val2}`.
+The key/value pairs will be printed in sorted order.
+
+[#converter-thread-id]
+==== Thread ID
+
+Outputs the ID of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadIdPatternConverter.html[`ThreadIdPatternConverter`] specifiers grammar
+[source,text]
+----
+T
+tid
+threadId
+----
+
+[#converter-thread-name]
+==== Thread name
+
+Outputs the name of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadNamePatternConverter.html[`ThreadNamePatternConverter`] specifier grammar
+[source,text]
+----
+t
+tn
+thread
+threadName
+----
+
+[#converter-thread-priority]
+==== Thread priority
+
+Outputs the priority of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadPriorityPatternConverter.html[`ThreadPriorityPatternConverter`] specifier grammar
+[source,text]
+----
+tp
+threadPriority
+----
+
+[#converter-uuid]
+==== UUID
+
+Includes either a random or a time-based UUID
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/UuidConverter.html[`UuidConverter`] specifier grammar
+[source,text]
+----
+u{RANDOM|TIME}
+uuid{RANDOM|TIME}
+----
+
+The time-based UUID is a Type 1 UUID generated using the MAC address of each host
+To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated.
+Because time-based UUIDs contain the MAC address and timestamp, they should be used with care.
+
+[#format-modifiers]
+=== Format modifiers
+
+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, if 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 `String#format()`, 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.
+
+[%header,cols="2m,2m,2m,2m,5"]
+|===
+|Pattern
+|Left justify
+|Min. width
+|Max. 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
+|N/A
+|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 the 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 the 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 the category name is longer than 30
+characters, then truncate from the end.
+|===
+
+[#jansi]
+=== ANSI styling on Windows
+
+ANSI escape sequences are supported natively on many platforms, but not by default on Windows.
+To enable ANSI support add the http://jansi.fusesource.org/[Jansi] dependency to your application, and set xref:manual/systemproperties.adoc#log4j.skipJansi[the `log4j.skipJansi` system property] to `false`.
+This allows Log4j to use Jansi to add ANSI escape codes when writing to the console.
+
+[NOTE]
+====
+Before 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 no longer automatically tries to load Jansi without explicit configuration from Log4j 2.10 onward.
+====
+
+[#garbage-free]
+=== Garbage-free configuration
+
+Pattern Layout with the following limited set of conversion patterns is garbage-free.
+Format modifiers to control such things as field width, padding, left, and right justification will not generate garbage.
+
+[%header,cols="2m,2"]
+|===
+|Pattern
+|Comment
+
+|xref:#converter-logger[%c\{precision} +
+%logger\{precision}]
+|
+
+|xref:#converter-date[%d +
+%date]
+|Only the predefined date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free
+
+|xref:#converter-encode[%enc\{pattern} +
+%encode\{pattern}]
+|
+
+|xref:#converter-equals[%equals\{pattern}\{test}\{substitution} +
+%equalsIgnoreCase\{pattern}\{test}\{substitution}]
+|
+
+|xref:#converter-highlight[%highlight\{pattern}\{style}]
+|Granted nested pattern is garbage-free
+
+|xref:#converter-map[%K\{key} +
+%map\{key} +
+%MAP\{key}]
+|
+
+|xref:#converter-message[%m +
+%msg +
+%message]
+|Garbage-free unless message text contains `${`
+
+|xref:#converter-marker[%marker]
+|
+
+|xref:#converter-marker[%markerSimpleName]
+|
+
+|xref:#converter-max-len[%maxLen +
+%maxLength]
+|
+
+|%n
+|
+
+|xref:#converter-nano[%N +
+%nano]
+|
+
+|xref:#converter-not-empty[%notEmpty\{pattern} +
+%varsNotEmpty\{pattern} +
+%variablesNotEmpty\{pattern}]
+|
+
+|xref:#converter-level[%p +
+%level]
+|
+
+|xref:#converter-relative[%r +
+%relative]
+|
+
+|xref:#converter-seq[%sn +
+%sequenceNumber]
+|
+
+|xref:#converter-style[%style\{pattern}{ANSI style}]
+|
+
+|xref:#converter-thread-id[%T +
+%tid +
+%threadId]
+|
+
+|xref:#converter-thread-name[%t +
+%tn +
+%thread +
+%threadName]
+|
+
+|xref:#converter-thread-priority[%tp]
+|
+
+|xref:#converter-thread-context-map[%X{key[,key2...\]} +
+%mdc{key[,key2...\]} +
+%MDC{key[,key2...\]}]
+|
+
+|literal text
+|Garbage-free unless it contains `${`
Review Comment:
We should probably add a note about lazy substitution.
Adding `${k8s:containerId}` is garbage-free, because it will be expanded at configuration time. Adding `$${date:hh:mm:ss.SSS}` is not, since it will be expanded at each log event.
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%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
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+You can enable xref:manual/lookups.adoc[] using `\{lookups}` and log messages like `${date:YYYY-MM-dd}` using lookups.
+This will replace the date template `YYYY-MM-dd` with an actual date.
+This can be confusing in many cases, and it's often both easier and more obvious to handle the lookup in code.
+This feature is disabled by default and the message string is logged untouched.
+
+[WARNING]
+====
+Users are strongly discouraged from using the lookups option.
+Doing so may allow uncontrolled user input containing lookups to take unintended actions.
+====
+
+[#converter-method]
+==== Method
+
+Outputs the method name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MethodLocationPatternConverter.html[`MethodLocationPatternConverter`] specifier grammar
+[source,text]
+----
+M
+method
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the method name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-nano]
+==== Nanoseconds
+
+Outputs the result of `System.nanoTime()` at the time the log event was created
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NanoTimePatternConverter.html[`NanoTimePatternConverter`] specifier grammar
+[source,text]
+----
+N
+nano
+----
+
+[#converter-not-empty]
+==== Not empty
+
+Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/VariablesNotEmptyReplacementConverter.html[`VariablesNotEmptyReplacementConverter`] specifier grammar
+[source,text]
+----
+variablesNotEmpty{pattern}
+varsNotEmpty{pattern}
+notEmpty{pattern}
+----
+
+For example:
+
+[source,text]
+----
+%notEmpty{[%marker]}
+----
+
+[#converter-pid]
+==== Process ID
+
+Outputs the process ID, if supported by the underlying platform
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ProcessIdPatternConverter.html[`ProcessIdPatternConverter`] specifier grammar
+[source,text]
+----
+pid{defaultValue}
+processId{defaultValue}
+----
+
+An optional `defaultValue` may be specified to be shown, if the platform does not support process IDs.
+
+[#converter-relative]
+==== Relative
+
+Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RelativeTimePatternConverter.html[`RelativeTimePatternConverter`] specifier grammar
+[source,text]
+----
+r
+relative
+----
+
+[#converter-repeat]
+==== Repeat
+
+Produces a string containing the requested number of instances of the specified string
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RepeatPatternConverter.html[`RepeatPatternConverter`] specifier grammar
+[source,text]
+----
+R{string}{count}
+repeat{string}{count}
+----
+
+For example, `%repeat{\*}\{2}` will result in the string `**`.
+
+[#converter-replace]
+==== Replace
+
+Replaces occurrences of a regular expression (`regex`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RegexReplacementConverter.html[`RegexReplacementConverter`] specifier grammar
+[source,text]
+----
+replace{pattern}{regex}{substitution}
+----
+
+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.
+
+[#converter-rootException]
+==== Root exception
+
+The same as xref:#converter-exception[the `exception` converter], but the stack trace is printed starting with the first exception in the causal chain that was thrown followed by each subsequent wrapping exception
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.html[`RootThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+rEx|rException|rThrowable
+ {
+ ["none" | "short" | "full" | depth]
+ [,filters(package,package,...)]
+ [,separator(separator)]
+ }
+ {ansi(
+ Key=Value,Value,...
+ Key=Value,Value,...
+ ...)
+ }
+ {suffix(pattern)}
+----
+
+The throwable conversion specifier can be followed by an option in the form `%rEx\{short}`, which will only output the first line of the `Throwable`, or `%rEx\{n}`, where the first `n` lines of the stack trace will be printed.
+
+Specifying `%rEx\{none}` or `%rEx\{0}` will suppress printing of the exception.
+
+Use `filters(packages)`, where `packages` is a list of package names to suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace, e.g., `separator(|)`.
+The default value is the `line.separator` system property, which is platform dependent.
+
+Use `rEx{suffix(pattern)}` to add the output of `pattern` to the output only when there is a `Throwable` to print.
+
+[#converter-seq]
+==== Sequence number
+
+Includes a sequence number that will be incremented in every event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/SequenceNumberPatternConverter.html[`SequenceNumberPatternConverter`] specifier grammar
+[source,text]
+----
+sn
+sequenceNumber
+----
+
+The counter is a static variable, so will only be unique within applications that share the same converter class object.
+
+[#converter-style]
+==== Style
+
+Use ANSI escape sequences to style the result of the enclosed pattern.
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/StyleConverter.html[`StyleConverter`] specifier grammar
+[source,text]
+----
+style{pattern}{ANSI style}
+----
+
+The style can consist of a comma-separated list of style names from the following table:
+
+[%header,cols="2m,3"]
+|===
+|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 the foreground color to black
+
+|Red or FG_Red
+|Set the foreground color to red
+
+|Green or FG_Green
+|Set the foreground color to green
+
+|Yellow or FG_Yellow
+|Set the foreground color to yellow
+
+|Blue or FG_Blue
+|Set the foreground color to blue
+
+|Magenta or FG_Magenta
+|Set the foreground color to magenta
+
+|Cyan or FG_Cyan
+|Set the foreground color to cyan
+
+|White or FG_White
+|Set the foreground color to white
+
+|Default or FG_Default
+|Set the foreground color to default (white)
+
+|BG_Black
+|Set the background color to black
+
+|BG_Red
+|Set the background color to red
+
+|BG_Green
+|Set the background color to green
+
+|BG_Yellow
+|Set the background color to yellow
+
+|BG_Blue
+|Set the background color to blue
+
+|BG_Magenta
+|Set the background color to magenta
+
+|BG_Cyan
+|Set the background color to cyan
+
+|BG_White
+|Set the background color to white
+|===
+
+For example:
+
+[source,text]
+----
+%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}
+----
+
+You can also combine styles:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}
+----
+
+[#converter-thread-context-stack]
+==== Thread context stack
+
+Outputs the xref:manual/thread-context.adoc[] stack (aka. Nested Diagnostic Context or NDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NdcPatternConverter.html[`NdcPatternConverter`] specifiers grammar
+[source,text]
+----
+x
+NDC
+----
+
+[#converter-thread-context-map]
+==== Thread context map
+
+Outputs the xref:manual/thread-context.adoc[] map (aka. Mapped Diagnostic Context or MDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MdcPatternConverter.html[`MdcPatternConverter`] specifiers grammar
+[source,text]
+----
+X{key[,key2...]}
+mdc{key[,key2...]}
+MDC{key[,key2...]}
+----
+
+The *X* conversion character can be followed by one or more keys for the map placed between braces, as in `%X\{clientNumber}`, where `clientNumber` is the key.
+The value in the MDC corresponding to the key will be output.
+
+If a list of keys is provided, such as `%X{name, number}`, then each key that is present in the thread context will be output using the format `{name=val1, number=val2}`.
+The key/value pairs will be printed in the order they appear in the list.
+
+If no sub-options are specified then the entire contents of the MDC key-value pair set is output using a format `{key1=val1, key2=val2}`.
+The key/value pairs will be printed in sorted order.
+
+[#converter-thread-id]
+==== Thread ID
+
+Outputs the ID of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadIdPatternConverter.html[`ThreadIdPatternConverter`] specifiers grammar
+[source,text]
+----
+T
+tid
+threadId
+----
+
+[#converter-thread-name]
+==== Thread name
+
+Outputs the name of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadNamePatternConverter.html[`ThreadNamePatternConverter`] specifier grammar
+[source,text]
+----
+t
+tn
+thread
+threadName
+----
+
+[#converter-thread-priority]
+==== Thread priority
+
+Outputs the priority of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadPriorityPatternConverter.html[`ThreadPriorityPatternConverter`] specifier grammar
+[source,text]
+----
+tp
+threadPriority
+----
+
+[#converter-uuid]
+==== UUID
+
+Includes either a random or a time-based UUID
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/UuidConverter.html[`UuidConverter`] specifier grammar
+[source,text]
+----
+u{RANDOM|TIME}
+uuid{RANDOM|TIME}
+----
+
+The time-based UUID is a Type 1 UUID generated using the MAC address of each host
+To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated.
+Because time-based UUIDs contain the MAC address and timestamp, they should be used with care.
+
+[#format-modifiers]
+=== Format modifiers
+
+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, if 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 `String#format()`, 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.
+
+[%header,cols="2m,2m,2m,2m,5"]
+|===
+|Pattern
+|Left justify
+|Min. width
+|Max. 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
+|N/A
+|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 the 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 the 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 the category name is longer than 30
+characters, then truncate from the end.
+|===
+
+[#jansi]
+=== ANSI styling on Windows
+
+ANSI escape sequences are supported natively on many platforms, but not by default on Windows.
+To enable ANSI support add the http://jansi.fusesource.org/[Jansi] dependency to your application, and set xref:manual/systemproperties.adoc#log4j.skipJansi[the `log4j.skipJansi` system property] to `false`.
+This allows Log4j to use Jansi to add ANSI escape codes when writing to the console.
+
+[NOTE]
+====
+Before 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 no longer automatically tries to load Jansi without explicit configuration from Log4j 2.10 onward.
+====
+
+[#garbage-free]
+=== Garbage-free configuration
+
+Pattern Layout with the following limited set of conversion patterns is garbage-free.
+Format modifiers to control such things as field width, padding, left, and right justification will not generate garbage.
+
+[%header,cols="2m,2"]
+|===
+|Pattern
+|Comment
+
+|xref:#converter-logger[%c\{precision} +
+%logger\{precision}]
+|
+
+|xref:#converter-date[%d +
+%date]
+|Only the predefined date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free
+
+|xref:#converter-encode[%enc\{pattern} +
+%encode\{pattern}]
+|
+
+|xref:#converter-equals[%equals\{pattern}\{test}\{substitution} +
+%equalsIgnoreCase\{pattern}\{test}\{substitution}]
+|
+
+|xref:#converter-highlight[%highlight\{pattern}\{style}]
+|Granted nested pattern is garbage-free
+
+|xref:#converter-map[%K\{key} +
+%map\{key} +
+%MAP\{key}]
+|
+
+|xref:#converter-message[%m +
+%msg +
+%message]
+|Garbage-free unless message text contains `${`
Review Comment:
I think this does not apply any more.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633692148
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
Review Comment:
@ppkarwasz, would you mind pushing this improvement in a commit to this branch, please?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633701810
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%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
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+You can enable xref:manual/lookups.adoc[] using `\{lookups}` and log messages like `${date:YYYY-MM-dd}` using lookups.
+This will replace the date template `YYYY-MM-dd` with an actual date.
+This can be confusing in many cases, and it's often both easier and more obvious to handle the lookup in code.
+This feature is disabled by default and the message string is logged untouched.
+
+[WARNING]
+====
+Users are strongly discouraged from using the lookups option.
+Doing so may allow uncontrolled user input containing lookups to take unintended actions.
+====
+
+[#converter-method]
+==== Method
+
+Outputs the method name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MethodLocationPatternConverter.html[`MethodLocationPatternConverter`] specifier grammar
+[source,text]
+----
+M
+method
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the method name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-nano]
+==== Nanoseconds
+
+Outputs the result of `System.nanoTime()` at the time the log event was created
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NanoTimePatternConverter.html[`NanoTimePatternConverter`] specifier grammar
+[source,text]
+----
+N
+nano
+----
+
+[#converter-not-empty]
+==== Not empty
+
+Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/VariablesNotEmptyReplacementConverter.html[`VariablesNotEmptyReplacementConverter`] specifier grammar
+[source,text]
+----
+variablesNotEmpty{pattern}
+varsNotEmpty{pattern}
+notEmpty{pattern}
+----
+
+For example:
+
+[source,text]
+----
+%notEmpty{[%marker]}
+----
+
+[#converter-pid]
+==== Process ID
+
+Outputs the process ID, if supported by the underlying platform
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ProcessIdPatternConverter.html[`ProcessIdPatternConverter`] specifier grammar
+[source,text]
+----
+pid{defaultValue}
+processId{defaultValue}
+----
+
+An optional `defaultValue` may be specified to be shown, if the platform does not support process IDs.
+
+[#converter-relative]
+==== Relative
+
+Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RelativeTimePatternConverter.html[`RelativeTimePatternConverter`] specifier grammar
+[source,text]
+----
+r
+relative
+----
+
+[#converter-repeat]
+==== Repeat
+
+Produces a string containing the requested number of instances of the specified string
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RepeatPatternConverter.html[`RepeatPatternConverter`] specifier grammar
+[source,text]
+----
+R{string}{count}
+repeat{string}{count}
+----
+
+For example, `%repeat{\*}\{2}` will result in the string `**`.
+
+[#converter-replace]
+==== Replace
+
+Replaces occurrences of a regular expression (`regex`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RegexReplacementConverter.html[`RegexReplacementConverter`] specifier grammar
+[source,text]
+----
+replace{pattern}{regex}{substitution}
+----
+
+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.
+
+[#converter-rootException]
+==== Root exception
+
+The same as xref:#converter-exception[the `exception` converter], but the stack trace is printed starting with the first exception in the causal chain that was thrown followed by each subsequent wrapping exception
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.html[`RootThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+rEx|rException|rThrowable
+ {
+ ["none" | "short" | "full" | depth]
+ [,filters(package,package,...)]
+ [,separator(separator)]
+ }
+ {ansi(
+ Key=Value,Value,...
+ Key=Value,Value,...
+ ...)
+ }
+ {suffix(pattern)}
+----
+
+The throwable conversion specifier can be followed by an option in the form `%rEx\{short}`, which will only output the first line of the `Throwable`, or `%rEx\{n}`, where the first `n` lines of the stack trace will be printed.
+
+Specifying `%rEx\{none}` or `%rEx\{0}` will suppress printing of the exception.
+
+Use `filters(packages)`, where `packages` is a list of package names to suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace, e.g., `separator(|)`.
+The default value is the `line.separator` system property, which is platform dependent.
+
+Use `rEx{suffix(pattern)}` to add the output of `pattern` to the output only when there is a `Throwable` to print.
+
+[#converter-seq]
+==== Sequence number
+
+Includes a sequence number that will be incremented in every event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/SequenceNumberPatternConverter.html[`SequenceNumberPatternConverter`] specifier grammar
+[source,text]
+----
+sn
+sequenceNumber
+----
+
+The counter is a static variable, so will only be unique within applications that share the same converter class object.
+
+[#converter-style]
+==== Style
+
+Use ANSI escape sequences to style the result of the enclosed pattern.
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/StyleConverter.html[`StyleConverter`] specifier grammar
+[source,text]
+----
+style{pattern}{ANSI style}
+----
+
+The style can consist of a comma-separated list of style names from the following table:
Review Comment:
I'd appreciate it if you can address this while improving the section on `%highlight`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633739365
##########
src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc:
##########
@@ -16,422 +16,479 @@
////
= JSON Template Layout
-`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON
-generating layout. It encodes ``LogEvent``s according to the structure described
-by the JSON template provided. In a nutshell, it shines with its
+JSON Template Layout is a customizable, xref:#performance[efficient], and xref:#faq-garbage-free[garbage-free] JSON generating layout.
+It encodes ``LogEvent``s according to the structure described by the JSON template provided.
+In a nutshell, it shines with its
-* Customizable JSON structure (see `eventTemplate[Uri]` and
- `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration] parameters)
+* Customizable JSON structure (see `eventTemplate[Uri]` and `stackTraceElementTemplate[Uri]` xref:#layout-config[layout configuration] parameters)
-* Customizable timestamp formatting (see xref:#event-template-resolver-timestamp[]
- event template resolver)
+* Customizable timestamp formatting (see xref:#event-template-resolver-timestamp[] event template resolver)
-* Feature rich exception formatting (see xref:#event-template-resolver-exception[]
- and xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
+* Feature rich exception formatting (see xref:#event-template-resolver-exception[] and xref:#event-template-resolver-exceptionRootCause[] event template resolvers)
* xref:manual/extending.adoc[Extensible plugin support]
* Customizable object xref:#recycling-strategy[recycling strategy]
+[TIP]
+====
+JSON Template Layout is intended for production deployments where the generated logs are expected to be delivered to an external log ingestion system such as Elasticsearch or Google Cloud Logging.
+While running tests or developing locally, you can use xref:manual/pattern-layout.adoc[] for human-readable log output.
+====
+
[#usage]
== Usage
-Adding `log4j-layout-template-json` artifact to your list of dependencies is
-enough to enable access to `JsonTemplateLayout` in your Log4j configuration:
+Adding `log4j-layout-template-json` artifact to your list of dependencies is enough to enable access to JSON Template Layout in your Log4j configuration:
+[tabs]
+====
+Maven::
++
[source,xml,subs="+attributes"]
----
-<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-layout-template-json</artifactId>
- <version>{log4j-layout-template-json-version}</version>
-</dependency>
+<project>
+
+ <!-- Assuming `log4j-bom` is imported --><!--1-->
+
+ <dependency>
+
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-layout-template-json</artifactId>
+ <scope>runtime</scope><!--2-->
+ </dependency>
+
+ </dependency>
+
+</project>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
----
+dependencies {
+
+ // Assuming `log4j-bom` is imported <1>
-For instance, given the following JSON template modelling
-https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification]
-(accessible via `classpath:EcsLayout.json`)
+ runtimeOnly // <2>
+ 'org.apache.logging.log4j:log4j-slf4j2-impl'
+
+}
+----
+====
+<1> Assuming you xref:manual/installation.adoc#bom[imported `org.apache.logging.log4j:log4j-bom`]
+<2> For applications, logging implementation dependencies are required at _runtime_.
+If you want to use JSON Template Layout for tests, you need to switch the scope to _test_.
+See xref:manual/installation.adoc[] for details.
+
+JSON Template Layout is primarily configured through an *event template* describing the structure log events should be JSON-encoded in.
+Event templates themselves are also JSON documents, where objects containing `$resolver` members, such as,
+
+[source,json]
+----
+{
+ "$resolver": "message", // <1>
+ "stringified": true // <2>
+}
+----
+<1> Indicating that this object should be replaced with the output from the xref:#event-template-resolver-message[`message` *event template resolver*]
+<2> Passing a configuration to the `message` event template resolver
+
+are interpreted by the JSON Template Layout compiler, and replaced with the referenced event or stack trace *template resolver* rendering that particular item.
+
+For instance, given the following event template stored in `MyLayout.json` in your classpath:
[source,json]
----
{
- "@timestamp": {
+ "instant": { // <1>
"$resolver": "timestamp",
"pattern": {
"format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
"timeZone": "UTC"
}
},
- "ecs.version": "1.2.0",
- "log.level": {
- "$resolver": "level",
- "field": "name"
- },
- "message": {
+ "someConstant": 1, // <2>
+ "message": { // <3>
"$resolver": "message",
"stringified": true
- },
- "process.thread.name": {
- "$resolver": "thread",
- "field": "name"
- },
- "log.logger": {
- "$resolver": "logger",
- "field": "name"
- },
- "labels": {
- "$resolver": "mdc",
- "flatten": true,
- "stringified": true
- },
- "tags": {
- "$resolver": "ndc"
- },
- "error.type": {
- "$resolver": "exception",
- "field": "className"
- },
- "error.message": {
- "$resolver": "exception",
- "field": "message"
- },
- "error.stack_trace": {
- "$resolver": "exception",
- "field": "stackTrace",
- "stackTrace": {
- "stringified": true
- }
}
}
----
+<1> Using xref:#event-template-resolver-timestamp[the `timestamp` event template resolver] to populate the `instant` field
+<2> Passing a constant that will be rendered as is
+<3> Using xref:#event-template-resolver-message[the `message` event template resolver] to populate the `message` field
-in combination with the below `log4j2.xml` configuration:
+in combination with the below layout configuration:
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.xml[`log4j2.xml`]
[source,xml]
----
-<JsonTemplateLayout eventTemplateUri="classpath:EcsLayout.json"/>
+include::example$manual/json-template-layout/usage/log4j2.xml[lines=26..26,indent=0]
----
-or with the below `log4j2.properties` configuration:
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/json-template-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
-[source,properties]
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
----
-appender.console.layout.type = JsonTemplateLayout
-appender.console.layout.eventTemplateUri = classpath:EcsLayout.json
+include::example$manual/json-template-layout/usage/log4j2.yaml[lines=22..23,indent=0]
----
-`JsonTemplateLayout` generates JSON as follows:
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/json-template-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/json-template-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+JSON Template Layout generates JSON as follows:
[source,json]
----
-{
- "@timestamp": "2017-05-25T19:56:23.370Z",
- "ecs.version": "1.2.0",
- "log.level": "ERROR",
- "message": "Hello, error!",
- "process.thread.name": "main",
- "log.logger": "org.apache.logging.log4j.JsonTemplateLayoutDemo",
- "error.type": "java.lang.RuntimeException",
- "error.message": "test",
- "error.stack_trace": "java.lang.RuntimeException: test\n\tat org.apache.logging.log4j.JsonTemplateLayoutDemo.main(JsonTemplateLayoutDemo.java:11)\n"
-}
+{"instant":"2017-05-25T19:56:23.370Z","someConstant":1,"message":"Hello, error!"} //<1>
----
+<1> JSON pretty-printing is not supported for performance reasons.
+
+Good news is *JSON Template Layout is perfectly production-ready without any configuration!*
+The event template defaults to `EcsLayout.json`, bundled in the classpath, modelling https://www.elastic.co/guide/en/ecs/current/ecs-reference.html[the Elastic Common Schema (ECS) specification].
+JSON Template Layout bundles several more xref:#event-templates[predefined event templates] modeling popular JSON-based log formats.
-[#layout-config]
-== Layout Configuration
+[#config]
+== Configuration
-`JsonTemplateLayout` is configured with the following parameters:
+This section explains how to configure JSON Template Layout plugin element in a Log4j configuration file.
-.`JsonTemplateLayout` parameters
-[cols="1m,1m,4"]
+[TIP]
+====
+Are you trying to implement your own event (or stack trace) template and looking for help on available resolvers?
+Please refer to xref:#template-config[] instead.
+====
+
+[#plugin-attrs]
+=== Plugin attributes
+
+JSON Template Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
|===
-| Parameter Name
-| Type
-| Description
-
-| charset
-| Charset
-| `Charset` used for `String` encoding
-
-| [[locationInfoEnabled]]locationInfoEnabled
-| boolean
-| toggles access to the `LogEvent` source; file name, line number, etc.
- (defaults to `false` set by `log4j.layout.jsonTemplate.locationInfoEnabled`
- property)
-
-| stackTraceEnabled
-| boolean
-| toggles access to the stack traces (defaults to `true` set by
- `log4j.layout.jsonTemplate.stackTraceEnabled` property)
-
-| eventTemplate
-| String
-| inline JSON template for rendering ``LogEvent``s (has priority over
- `eventTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplate` property)
-
-| eventTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``LogEvent``s (defaults to
- `classpath:EcsLayout.json` set by `log4j.layout.jsonTemplate.eventTemplateUri`
- property)
-
-| eventTemplateRootObjectKey
-| String
-| if present, the event template is put into a JSON object composed of a single
- member with the provided key (defaults to `null` set by
- `log4j.layout.jsonTemplate.eventTemplateRootObjectKey`
- property)
-
-| eventTemplateAdditionalField
-| EventTemplateAdditionalField[]
-| additional key-value pairs appended to the root of the event template
-
-| stackTraceElementTemplate
-| String
-| inline JSON template for rendering ``StackTraceElement``s (has priority over
- `stackTraceElementTemplateUri`, defaults to `null` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplate` property)
-
-| stackTraceElementTemplateUri
-| String
-| URI pointing to the JSON template for rendering ``StackTraceElement``s
- (defaults to `classpath:StackTraceElementLayout.json` set by
- `log4j.layout.jsonTemplate.stackTraceElementTemplateUri` property)
-
-| eventDelimiter
-| String
-| delimiter used for separating rendered ``LogEvent``s (defaults to
- `System.lineSeparator()` set by `log4j.layout.jsonTemplate.eventDelimiter`
- property)
-
-| nullEventDelimiterEnabled
-| boolean
-| append `\0` (`null`) character to the end of every `eventDelimiter`
- separating rendered ``LogEvent``s (defaults to `false` set by
- `log4j.layout.jsonTemplate.nullEventDelimiterEnabled` property)
-
-| [[maxStringLength]] maxStringLength
-| int
-| truncate string values longer than the specified limit (defaults to 16384 set
- by `log4j.layout.jsonTemplate.maxStringLength` property)
-
-| truncatedStringSuffix
-| String
-| suffix to append to strings truncated due to exceeding `maxStringLength`
- (defaults to `…` set by `log4j.layout.jsonTemplate.truncatedStringSuffix`
- property)
-
-| recyclerFactory
-| RecyclerFactory
-| recycling strategy that can either be `dummy`, `threadLocal`, or `queue`
- (set by `log4j.layout.jsonTemplate.recyclerFactory` property)
+|Type |`Charset`
+|Default value |`UTF-8`
+|Configuration property |`log4j.layout.jsonTemplate.charset`
|===
-[#additional-event-template-fields]
-=== Additional event template fields
+`Charset` used for encoding the produced JSON into bytes
Review Comment:
Fixed in c5f012682d393ddb372a8b3cb0d2d184440a30f0.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633691789
##########
src/site/antora/modules/ROOT/pages/manual/layouts.adoc:
##########
@@ -14,2120 +14,863 @@
See the License for the specific language governing permissions and
limitations under the License.
////
-= Layouts
-An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be consuming the log event.
-In Log4j 1.x and Logback Layouts were expected to transform an event into a String.
-In Log4j 2 Layouts return a byte array.
-This allows the result of the Layout to be useful in many more types of Appenders.
-However, this means you need to configure most Layouts with a
-https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[`Charset`]
-to ensure the byte array contains correct values.
+= Layouts
-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.
+An xref:manual/appenders.adoc[appender] uses a *layout* to encode a link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[`LogEvent`] into a form that meets the needs of whatever will be consuming the log event.
+This page will try to answer following questions:
-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.
+* xref:#concerns[What are some common concerns shared by all predefined layouts?]
+* xref:#collection[Which layouts does Log4j provide?]
+* xref:#extending[How can you create custom layouts?]
-[#common-concerns]
+[#concerns]
== Common concerns
+This section introduces you to some common concerns shared by almost all xref:#collection[predefined layouts] that you need to be aware of while using them.
+
+[#charset]
+=== Character encoding
+
+All xref:#collection[predefined layouts] produce `String` that eventually get converted into a `byte[]` using the https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html[`Charset`] configured.
+While doing so, they use `UTF-8` by default.
Review Comment:
Except `SerializedLayout` and `JsonTemplateLayout`, all layouts extend from `AbstractStringLayout`, which defaults the `charset` to `UTF-8`. `PatternLayout` deviates from this and uses the platform default due to [LOG4J2-783](https://issues.apache.org/jira/browse/LOG4J2-783). I will rephrase this as follows:
> While doing so, unless an explicit encoding configuration is stated, they use `UTF-8` by default.
Fixed in 74a6ae462b201808bc06ca86888fc589b3adccd4.
For the record, `pattern-layout.adoc` was explicitly stating that `charset` defaults to the platform default.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#issuecomment-2159201471
> We could also include a link to the plugin reference, whenever we deal with a plugin, so that users can find the errors in the documentation themselves.
@ppkarwasz, added in 0cf6c346e775b6307a3b0d7f793835c94f6f2761.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633691523
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
Review Comment:
Fixed in b95d668f7e9dfe7a7d5b7787be58f4a7b9b65a15.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633701037
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%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
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+You can enable xref:manual/lookups.adoc[] using `\{lookups}` and log messages like `${date:YYYY-MM-dd}` using lookups.
Review Comment:
Fixed in 76f77b59edc56a27ae277dbcd8c605c0a04841ff.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633738384
##########
src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc:
##########
@@ -1983,10 +2046,10 @@ To get the most out of it, mind the following checklist:
[#faq-lookups]
=== Are lookups supported in templates?
-Yes, xref:manual/lookups.adoc[lookups] (e.g., `${java:version}`,
-`${env:USER}`, `${date:MM-dd-yyyy}`) are supported in string
-literals of templates. Though note that they are not garbage-free.
+Yes, xref:manual/lookups.adoc[lookups] (e.g., `${java:version}`, `${env:USER}`, `${date:MM-dd-yyyy}`) are supported in string literals of templates.
+Though note that they are not garbage-free.
Review Comment:
Fixed in c5f012682d393ddb372a8b3cb0d2d184440a30f0.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1633707216
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%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
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+You can enable xref:manual/lookups.adoc[] using `\{lookups}` and log messages like `${date:YYYY-MM-dd}` using lookups.
+This will replace the date template `YYYY-MM-dd` with an actual date.
+This can be confusing in many cases, and it's often both easier and more obvious to handle the lookup in code.
+This feature is disabled by default and the message string is logged untouched.
+
+[WARNING]
+====
+Users are strongly discouraged from using the lookups option.
+Doing so may allow uncontrolled user input containing lookups to take unintended actions.
+====
+
+[#converter-method]
+==== Method
+
+Outputs the method name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MethodLocationPatternConverter.html[`MethodLocationPatternConverter`] specifier grammar
+[source,text]
+----
+M
+method
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the method name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-nano]
+==== Nanoseconds
+
+Outputs the result of `System.nanoTime()` at the time the log event was created
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NanoTimePatternConverter.html[`NanoTimePatternConverter`] specifier grammar
+[source,text]
+----
+N
+nano
+----
+
+[#converter-not-empty]
+==== Not empty
+
+Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/VariablesNotEmptyReplacementConverter.html[`VariablesNotEmptyReplacementConverter`] specifier grammar
+[source,text]
+----
+variablesNotEmpty{pattern}
+varsNotEmpty{pattern}
+notEmpty{pattern}
+----
+
+For example:
+
+[source,text]
+----
+%notEmpty{[%marker]}
+----
+
+[#converter-pid]
+==== Process ID
+
+Outputs the process ID, if supported by the underlying platform
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ProcessIdPatternConverter.html[`ProcessIdPatternConverter`] specifier grammar
+[source,text]
+----
+pid{defaultValue}
+processId{defaultValue}
+----
+
+An optional `defaultValue` may be specified to be shown, if the platform does not support process IDs.
+
+[#converter-relative]
+==== Relative
+
+Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RelativeTimePatternConverter.html[`RelativeTimePatternConverter`] specifier grammar
+[source,text]
+----
+r
+relative
+----
+
+[#converter-repeat]
+==== Repeat
+
+Produces a string containing the requested number of instances of the specified string
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RepeatPatternConverter.html[`RepeatPatternConverter`] specifier grammar
+[source,text]
+----
+R{string}{count}
+repeat{string}{count}
+----
+
+For example, `%repeat{\*}\{2}` will result in the string `**`.
+
+[#converter-replace]
+==== Replace
+
+Replaces occurrences of a regular expression (`regex`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RegexReplacementConverter.html[`RegexReplacementConverter`] specifier grammar
+[source,text]
+----
+replace{pattern}{regex}{substitution}
+----
+
+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.
+
+[#converter-rootException]
+==== Root exception
+
+The same as xref:#converter-exception[the `exception` converter], but the stack trace is printed starting with the first exception in the causal chain that was thrown followed by each subsequent wrapping exception
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.html[`RootThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+rEx|rException|rThrowable
+ {
+ ["none" | "short" | "full" | depth]
+ [,filters(package,package,...)]
+ [,separator(separator)]
+ }
+ {ansi(
+ Key=Value,Value,...
+ Key=Value,Value,...
+ ...)
+ }
+ {suffix(pattern)}
+----
+
+The throwable conversion specifier can be followed by an option in the form `%rEx\{short}`, which will only output the first line of the `Throwable`, or `%rEx\{n}`, where the first `n` lines of the stack trace will be printed.
+
+Specifying `%rEx\{none}` or `%rEx\{0}` will suppress printing of the exception.
+
+Use `filters(packages)`, where `packages` is a list of package names to suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace, e.g., `separator(|)`.
+The default value is the `line.separator` system property, which is platform dependent.
+
+Use `rEx{suffix(pattern)}` to add the output of `pattern` to the output only when there is a `Throwable` to print.
+
+[#converter-seq]
+==== Sequence number
+
+Includes a sequence number that will be incremented in every event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/SequenceNumberPatternConverter.html[`SequenceNumberPatternConverter`] specifier grammar
+[source,text]
+----
+sn
+sequenceNumber
+----
+
+The counter is a static variable, so will only be unique within applications that share the same converter class object.
+
+[#converter-style]
+==== Style
+
+Use ANSI escape sequences to style the result of the enclosed pattern.
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/StyleConverter.html[`StyleConverter`] specifier grammar
+[source,text]
+----
+style{pattern}{ANSI style}
+----
+
+The style can consist of a comma-separated list of style names from the following table:
+
+[%header,cols="2m,3"]
+|===
+|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 the foreground color to black
+
+|Red or FG_Red
+|Set the foreground color to red
+
+|Green or FG_Green
+|Set the foreground color to green
+
+|Yellow or FG_Yellow
+|Set the foreground color to yellow
+
+|Blue or FG_Blue
+|Set the foreground color to blue
+
+|Magenta or FG_Magenta
+|Set the foreground color to magenta
+
+|Cyan or FG_Cyan
+|Set the foreground color to cyan
+
+|White or FG_White
+|Set the foreground color to white
+
+|Default or FG_Default
+|Set the foreground color to default (white)
+
+|BG_Black
+|Set the background color to black
+
+|BG_Red
+|Set the background color to red
+
+|BG_Green
+|Set the background color to green
+
+|BG_Yellow
+|Set the background color to yellow
+
+|BG_Blue
+|Set the background color to blue
+
+|BG_Magenta
+|Set the background color to magenta
+
+|BG_Cyan
+|Set the background color to cyan
+
+|BG_White
+|Set the background color to white
+|===
+
+For example:
+
+[source,text]
+----
+%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}
+----
+
+You can also combine styles:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}
+----
+
+[#converter-thread-context-stack]
+==== Thread context stack
+
+Outputs the xref:manual/thread-context.adoc[] stack (aka. Nested Diagnostic Context or NDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NdcPatternConverter.html[`NdcPatternConverter`] specifiers grammar
+[source,text]
+----
+x
+NDC
+----
+
+[#converter-thread-context-map]
+==== Thread context map
+
+Outputs the xref:manual/thread-context.adoc[] map (aka. Mapped Diagnostic Context or MDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MdcPatternConverter.html[`MdcPatternConverter`] specifiers grammar
+[source,text]
+----
+X{key[,key2...]}
+mdc{key[,key2...]}
+MDC{key[,key2...]}
+----
+
+The *X* conversion character can be followed by one or more keys for the map placed between braces, as in `%X\{clientNumber}`, where `clientNumber` is the key.
+The value in the MDC corresponding to the key will be output.
+
+If a list of keys is provided, such as `%X{name, number}`, then each key that is present in the thread context will be output using the format `{name=val1, number=val2}`.
+The key/value pairs will be printed in the order they appear in the list.
+
+If no sub-options are specified then the entire contents of the MDC key-value pair set is output using a format `{key1=val1, key2=val2}`.
+The key/value pairs will be printed in sorted order.
+
+[#converter-thread-id]
+==== Thread ID
+
+Outputs the ID of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadIdPatternConverter.html[`ThreadIdPatternConverter`] specifiers grammar
+[source,text]
+----
+T
+tid
+threadId
+----
+
+[#converter-thread-name]
+==== Thread name
+
+Outputs the name of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadNamePatternConverter.html[`ThreadNamePatternConverter`] specifier grammar
+[source,text]
+----
+t
+tn
+thread
+threadName
+----
+
+[#converter-thread-priority]
+==== Thread priority
+
+Outputs the priority of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadPriorityPatternConverter.html[`ThreadPriorityPatternConverter`] specifier grammar
+[source,text]
+----
+tp
+threadPriority
+----
+
+[#converter-uuid]
+==== UUID
+
+Includes either a random or a time-based UUID
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/UuidConverter.html[`UuidConverter`] specifier grammar
+[source,text]
+----
+u{RANDOM|TIME}
+uuid{RANDOM|TIME}
+----
+
+The time-based UUID is a Type 1 UUID generated using the MAC address of each host
+To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated.
+Because time-based UUIDs contain the MAC address and timestamp, they should be used with care.
+
+[#format-modifiers]
+=== Format modifiers
+
+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, if 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 `String#format()`, 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.
+
+[%header,cols="2m,2m,2m,2m,5"]
+|===
+|Pattern
+|Left justify
+|Min. width
+|Max. 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
+|N/A
+|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 the 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 the 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 the category name is longer than 30
+characters, then truncate from the end.
+|===
+
+[#jansi]
+=== ANSI styling on Windows
+
+ANSI escape sequences are supported natively on many platforms, but not by default on Windows.
+To enable ANSI support add the http://jansi.fusesource.org/[Jansi] dependency to your application, and set xref:manual/systemproperties.adoc#log4j.skipJansi[the `log4j.skipJansi` system property] to `false`.
+This allows Log4j to use Jansi to add ANSI escape codes when writing to the console.
+
+[NOTE]
+====
+Before 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 no longer automatically tries to load Jansi without explicit configuration from Log4j 2.10 onward.
+====
+
+[#garbage-free]
+=== Garbage-free configuration
+
+Pattern Layout with the following limited set of conversion patterns is garbage-free.
+Format modifiers to control such things as field width, padding, left, and right justification will not generate garbage.
+
+[%header,cols="2m,2"]
+|===
+|Pattern
+|Comment
+
+|xref:#converter-logger[%c\{precision} +
+%logger\{precision}]
+|
+
+|xref:#converter-date[%d +
+%date]
+|Only the predefined date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free
+
+|xref:#converter-encode[%enc\{pattern} +
+%encode\{pattern}]
+|
+
+|xref:#converter-equals[%equals\{pattern}\{test}\{substitution} +
+%equalsIgnoreCase\{pattern}\{test}\{substitution}]
+|
+
+|xref:#converter-highlight[%highlight\{pattern}\{style}]
+|Granted nested pattern is garbage-free
+
+|xref:#converter-map[%K\{key} +
+%map\{key} +
+%MAP\{key}]
+|
+
+|xref:#converter-message[%m +
+%msg +
+%message]
+|Garbage-free unless message text contains `${`
+
+|xref:#converter-marker[%marker]
+|
+
+|xref:#converter-marker[%markerSimpleName]
+|
+
+|xref:#converter-max-len[%maxLen +
+%maxLength]
+|
+
+|%n
+|
+
+|xref:#converter-nano[%N +
+%nano]
+|
+
+|xref:#converter-not-empty[%notEmpty\{pattern} +
+%varsNotEmpty\{pattern} +
+%variablesNotEmpty\{pattern}]
+|
+
+|xref:#converter-level[%p +
+%level]
+|
+
+|xref:#converter-relative[%r +
+%relative]
+|
+
+|xref:#converter-seq[%sn +
+%sequenceNumber]
+|
+
+|xref:#converter-style[%style\{pattern}{ANSI style}]
+|
+
+|xref:#converter-thread-id[%T +
+%tid +
+%threadId]
+|
+
+|xref:#converter-thread-name[%t +
+%tn +
+%thread +
+%threadName]
+|
+
+|xref:#converter-thread-priority[%tp]
+|
+
+|xref:#converter-thread-context-map[%X{key[,key2...\]} +
+%mdc{key[,key2...\]} +
+%MDC{key[,key2...\]}]
+|
+
+|literal text
+|Garbage-free unless it contains `${`
Review Comment:
Fixed in f77b5c0fce41b93da448f5d78fe902a09f970092.
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%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
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+You can enable xref:manual/lookups.adoc[] using `\{lookups}` and log messages like `${date:YYYY-MM-dd}` using lookups.
+This will replace the date template `YYYY-MM-dd` with an actual date.
+This can be confusing in many cases, and it's often both easier and more obvious to handle the lookup in code.
+This feature is disabled by default and the message string is logged untouched.
+
+[WARNING]
+====
+Users are strongly discouraged from using the lookups option.
+Doing so may allow uncontrolled user input containing lookups to take unintended actions.
+====
+
+[#converter-method]
+==== Method
+
+Outputs the method name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MethodLocationPatternConverter.html[`MethodLocationPatternConverter`] specifier grammar
+[source,text]
+----
+M
+method
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the method name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-nano]
+==== Nanoseconds
+
+Outputs the result of `System.nanoTime()` at the time the log event was created
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NanoTimePatternConverter.html[`NanoTimePatternConverter`] specifier grammar
+[source,text]
+----
+N
+nano
+----
+
+[#converter-not-empty]
+==== Not empty
+
+Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/VariablesNotEmptyReplacementConverter.html[`VariablesNotEmptyReplacementConverter`] specifier grammar
+[source,text]
+----
+variablesNotEmpty{pattern}
+varsNotEmpty{pattern}
+notEmpty{pattern}
+----
+
+For example:
+
+[source,text]
+----
+%notEmpty{[%marker]}
+----
+
+[#converter-pid]
+==== Process ID
+
+Outputs the process ID, if supported by the underlying platform
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ProcessIdPatternConverter.html[`ProcessIdPatternConverter`] specifier grammar
+[source,text]
+----
+pid{defaultValue}
+processId{defaultValue}
+----
+
+An optional `defaultValue` may be specified to be shown, if the platform does not support process IDs.
+
+[#converter-relative]
+==== Relative
+
+Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RelativeTimePatternConverter.html[`RelativeTimePatternConverter`] specifier grammar
+[source,text]
+----
+r
+relative
+----
+
+[#converter-repeat]
+==== Repeat
+
+Produces a string containing the requested number of instances of the specified string
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RepeatPatternConverter.html[`RepeatPatternConverter`] specifier grammar
+[source,text]
+----
+R{string}{count}
+repeat{string}{count}
+----
+
+For example, `%repeat{\*}\{2}` will result in the string `**`.
+
+[#converter-replace]
+==== Replace
+
+Replaces occurrences of a regular expression (`regex`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RegexReplacementConverter.html[`RegexReplacementConverter`] specifier grammar
+[source,text]
+----
+replace{pattern}{regex}{substitution}
+----
+
+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.
+
+[#converter-rootException]
+==== Root exception
+
+The same as xref:#converter-exception[the `exception` converter], but the stack trace is printed starting with the first exception in the causal chain that was thrown followed by each subsequent wrapping exception
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.html[`RootThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+rEx|rException|rThrowable
+ {
+ ["none" | "short" | "full" | depth]
+ [,filters(package,package,...)]
+ [,separator(separator)]
+ }
+ {ansi(
+ Key=Value,Value,...
+ Key=Value,Value,...
+ ...)
+ }
+ {suffix(pattern)}
+----
+
+The throwable conversion specifier can be followed by an option in the form `%rEx\{short}`, which will only output the first line of the `Throwable`, or `%rEx\{n}`, where the first `n` lines of the stack trace will be printed.
+
+Specifying `%rEx\{none}` or `%rEx\{0}` will suppress printing of the exception.
+
+Use `filters(packages)`, where `packages` is a list of package names to suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace, e.g., `separator(|)`.
+The default value is the `line.separator` system property, which is platform dependent.
+
+Use `rEx{suffix(pattern)}` to add the output of `pattern` to the output only when there is a `Throwable` to print.
+
+[#converter-seq]
+==== Sequence number
+
+Includes a sequence number that will be incremented in every event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/SequenceNumberPatternConverter.html[`SequenceNumberPatternConverter`] specifier grammar
+[source,text]
+----
+sn
+sequenceNumber
+----
+
+The counter is a static variable, so will only be unique within applications that share the same converter class object.
+
+[#converter-style]
+==== Style
+
+Use ANSI escape sequences to style the result of the enclosed pattern.
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/StyleConverter.html[`StyleConverter`] specifier grammar
+[source,text]
+----
+style{pattern}{ANSI style}
+----
+
+The style can consist of a comma-separated list of style names from the following table:
+
+[%header,cols="2m,3"]
+|===
+|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 the foreground color to black
+
+|Red or FG_Red
+|Set the foreground color to red
+
+|Green or FG_Green
+|Set the foreground color to green
+
+|Yellow or FG_Yellow
+|Set the foreground color to yellow
+
+|Blue or FG_Blue
+|Set the foreground color to blue
+
+|Magenta or FG_Magenta
+|Set the foreground color to magenta
+
+|Cyan or FG_Cyan
+|Set the foreground color to cyan
+
+|White or FG_White
+|Set the foreground color to white
+
+|Default or FG_Default
+|Set the foreground color to default (white)
+
+|BG_Black
+|Set the background color to black
+
+|BG_Red
+|Set the background color to red
+
+|BG_Green
+|Set the background color to green
+
+|BG_Yellow
+|Set the background color to yellow
+
+|BG_Blue
+|Set the background color to blue
+
+|BG_Magenta
+|Set the background color to magenta
+
+|BG_Cyan
+|Set the background color to cyan
+
+|BG_White
+|Set the background color to white
+|===
+
+For example:
+
+[source,text]
+----
+%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}
+----
+
+You can also combine styles:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}
+----
+
+[#converter-thread-context-stack]
+==== Thread context stack
+
+Outputs the xref:manual/thread-context.adoc[] stack (aka. Nested Diagnostic Context or NDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NdcPatternConverter.html[`NdcPatternConverter`] specifiers grammar
+[source,text]
+----
+x
+NDC
+----
+
+[#converter-thread-context-map]
+==== Thread context map
+
+Outputs the xref:manual/thread-context.adoc[] map (aka. Mapped Diagnostic Context or MDC) associated with the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MdcPatternConverter.html[`MdcPatternConverter`] specifiers grammar
+[source,text]
+----
+X{key[,key2...]}
+mdc{key[,key2...]}
+MDC{key[,key2...]}
+----
+
+The *X* conversion character can be followed by one or more keys for the map placed between braces, as in `%X\{clientNumber}`, where `clientNumber` is the key.
+The value in the MDC corresponding to the key will be output.
+
+If a list of keys is provided, such as `%X{name, number}`, then each key that is present in the thread context will be output using the format `{name=val1, number=val2}`.
+The key/value pairs will be printed in the order they appear in the list.
+
+If no sub-options are specified then the entire contents of the MDC key-value pair set is output using a format `{key1=val1, key2=val2}`.
+The key/value pairs will be printed in sorted order.
+
+[#converter-thread-id]
+==== Thread ID
+
+Outputs the ID of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadIdPatternConverter.html[`ThreadIdPatternConverter`] specifiers grammar
+[source,text]
+----
+T
+tid
+threadId
+----
+
+[#converter-thread-name]
+==== Thread name
+
+Outputs the name of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadNamePatternConverter.html[`ThreadNamePatternConverter`] specifier grammar
+[source,text]
+----
+t
+tn
+thread
+threadName
+----
+
+[#converter-thread-priority]
+==== Thread priority
+
+Outputs the priority of the thread that generated the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThreadPriorityPatternConverter.html[`ThreadPriorityPatternConverter`] specifier grammar
+[source,text]
+----
+tp
+threadPriority
+----
+
+[#converter-uuid]
+==== UUID
+
+Includes either a random or a time-based UUID
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/UuidConverter.html[`UuidConverter`] specifier grammar
+[source,text]
+----
+u{RANDOM|TIME}
+uuid{RANDOM|TIME}
+----
+
+The time-based UUID is a Type 1 UUID generated using the MAC address of each host
+To ensure uniqueness across multiple JVMs and/or class loaders on the same host, a random number between 0 and 16,384 will be associated with each instance of the UUID generator class, and included in each time-based UUID generated.
+Because time-based UUIDs contain the MAC address and timestamp, they should be used with care.
+
+[#format-modifiers]
+=== Format modifiers
+
+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, if 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 `String#format()`, 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.
+
+[%header,cols="2m,2m,2m,2m,5"]
+|===
+|Pattern
+|Left justify
+|Min. width
+|Max. 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
+|N/A
+|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 the 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 the 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 the category name is longer than 30
+characters, then truncate from the end.
+|===
+
+[#jansi]
+=== ANSI styling on Windows
+
+ANSI escape sequences are supported natively on many platforms, but not by default on Windows.
+To enable ANSI support add the http://jansi.fusesource.org/[Jansi] dependency to your application, and set xref:manual/systemproperties.adoc#log4j.skipJansi[the `log4j.skipJansi` system property] to `false`.
+This allows Log4j to use Jansi to add ANSI escape codes when writing to the console.
+
+[NOTE]
+====
+Before 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 no longer automatically tries to load Jansi without explicit configuration from Log4j 2.10 onward.
+====
+
+[#garbage-free]
+=== Garbage-free configuration
+
+Pattern Layout with the following limited set of conversion patterns is garbage-free.
+Format modifiers to control such things as field width, padding, left, and right justification will not generate garbage.
+
+[%header,cols="2m,2"]
+|===
+|Pattern
+|Comment
+
+|xref:#converter-logger[%c\{precision} +
+%logger\{precision}]
+|
+
+|xref:#converter-date[%d +
+%date]
+|Only the predefined date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free
+
+|xref:#converter-encode[%enc\{pattern} +
+%encode\{pattern}]
+|
+
+|xref:#converter-equals[%equals\{pattern}\{test}\{substitution} +
+%equalsIgnoreCase\{pattern}\{test}\{substitution}]
+|
+
+|xref:#converter-highlight[%highlight\{pattern}\{style}]
+|Granted nested pattern is garbage-free
+
+|xref:#converter-map[%K\{key} +
+%map\{key} +
+%MAP\{key}]
+|
+
+|xref:#converter-message[%m +
+%msg +
+%message]
+|Garbage-free unless message text contains `${`
Review Comment:
Fixed in f77b5c0fce41b93da448f5d78fe902a09f970092.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1634880198
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
+
+See the table below for abbreviation examples:
+
+[%header,cols="1m,3m,3m"]
+|===
+|Pattern
+|Logger name
+|Output
+
+|%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
+
+|%c{1.1.1.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.2.*}
+|org.apache.commons.test.Foo
+|o.a.c.test.Foo
+
+|%c{1.3.*}
+|org.apache.commons.test.Foo
+|o.a.commons.test.Foo
+
+|%c{1.8.*}
+|org.apache.commons.test.Foo
+|org.apache.commons.test.Foo
+|===
+
+[#converter-marker]
+==== Marker
+
+Outputs the marker, if one is present
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerPatternConverter.html[`MarkerPatternConverter`] and .link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MarkerSimpleNamePatternConverter.html[`MarkerSimpleNamePatternConverter`] specifiers' grammar
+[source,text]
+----
+marker
+markerSimpleName
+----
+
+`marker` outputs the full name of the marker, including its parents.
+Whereas, `markerSimpleName` outputs the simple name of the marker without its parents.
+
+[#converter-map]
+==== Map
+
+Outputs the entries in a xref:manual/messages.adoc#MapMessage[`MapMessage`], if one is present in the event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MapPatternConverter.html[`MapPatternConverter`] specifier grammar
+[source,text]
+----
+K{key}
+map{key}
+MAP{key}
+----
+
+The `K` conversion character can be followed by the key for the map placed between braces, as in `%K\{clientNumber}`, where `clientNumber` is the key.
+The value of the map corresponding to the key will be output.
+If no additional sub-option is specified, then all map entries are output using a `{{key1,val1},{key2,val2}}` format.
+
+[#converter-max-len]
+==== Max. length
+
+Outputs the result of evaluating the given pattern and truncating the result
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MaxLegthConverter.html[`MaxLengthConverter`] specifier grammar
+[source,text]
+----
+maxLen{pattern}{length}
+maxLength{pattern}{length}
+----
+
+If the length is greater than 20, then the output will contain a trailing ellipsis.
+If the provided length is invalid, a default value of 100 is used.
+
+For instance, `%maxLen{%p: %c\{1} - %m%notEmpty{ =>%ex\{short}}}\{160}` will be limited to 160 characters with a trailing ellipsis.
+`%maxLen{%m}\{20}` will be limited to 20 characters and no trailing ellipsis.
+
+[#converter-message]
+==== Message
+
+Outputs the message associated with the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MessagePatternConverter.html[`MessagePatternConverter`] specifier grammar
+[source,text]
+----
+m{lookups}{ansi}
+msg{lookups}{ansi}
+message{lookups}{ansi}
+----
+
+Add `\{ansi}` to render messages with ANSI escape codes.
+Windows users should refer to xref:#jansi[].
+
+The default syntax for embedded ANSI codes is:
+
+[source,text]
+----
+@\|code(,code)* text\|@
+----
+
+For example, to render the message `Hello` in green, use:
+
+[source,text]
+----
+@\|green Hello\|@
+----
+
+To render the message `Hello` in bold and red, use:
+
+[source,text]
+----
+@\|bold,red Warning!\|@
+----
+
+You can also define custom style names in the configuration with the syntax:
+
+[source,text]
+----
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+----
+
+For example:
+
+[source,text]
+----
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+----
+
+The call site can look like this:
+
+[source,text]
+----
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+----
+
+You can enable xref:manual/lookups.adoc[] using `\{lookups}` and log messages like `${date:YYYY-MM-dd}` using lookups.
+This will replace the date template `YYYY-MM-dd` with an actual date.
+This can be confusing in many cases, and it's often both easier and more obvious to handle the lookup in code.
+This feature is disabled by default and the message string is logged untouched.
+
+[WARNING]
+====
+Users are strongly discouraged from using the lookups option.
+Doing so may allow uncontrolled user input containing lookups to take unintended actions.
+====
+
+[#converter-method]
+==== Method
+
+Outputs the method name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/MethodLocationPatternConverter.html[`MethodLocationPatternConverter`] specifier grammar
+[source,text]
+----
+M
+method
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the method name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-nano]
+==== Nanoseconds
+
+Outputs the result of `System.nanoTime()` at the time the log event was created
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/NanoTimePatternConverter.html[`NanoTimePatternConverter`] specifier grammar
+[source,text]
+----
+N
+nano
+----
+
+[#converter-not-empty]
+==== Not empty
+
+Outputs the result of evaluating the pattern, if and only if all variables in the pattern are not empty
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/VariablesNotEmptyReplacementConverter.html[`VariablesNotEmptyReplacementConverter`] specifier grammar
+[source,text]
+----
+variablesNotEmpty{pattern}
+varsNotEmpty{pattern}
+notEmpty{pattern}
+----
+
+For example:
+
+[source,text]
+----
+%notEmpty{[%marker]}
+----
+
+[#converter-pid]
+==== Process ID
+
+Outputs the process ID, if supported by the underlying platform
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ProcessIdPatternConverter.html[`ProcessIdPatternConverter`] specifier grammar
+[source,text]
+----
+pid{defaultValue}
+processId{defaultValue}
+----
+
+An optional `defaultValue` may be specified to be shown, if the platform does not support process IDs.
+
+[#converter-relative]
+==== Relative
+
+Outputs the number of milliseconds elapsed since the JVM was started until the creation of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RelativeTimePatternConverter.html[`RelativeTimePatternConverter`] specifier grammar
+[source,text]
+----
+r
+relative
+----
+
+[#converter-repeat]
+==== Repeat
+
+Produces a string containing the requested number of instances of the specified string
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RepeatPatternConverter.html[`RepeatPatternConverter`] specifier grammar
+[source,text]
+----
+R{string}{count}
+repeat{string}{count}
+----
+
+For example, `%repeat{\*}\{2}` will result in the string `**`.
+
+[#converter-replace]
+==== Replace
+
+Replaces occurrences of a regular expression (`regex`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RegexReplacementConverter.html[`RegexReplacementConverter`] specifier grammar
+[source,text]
+----
+replace{pattern}{regex}{substitution}
+----
+
+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.
+
+[#converter-rootException]
+==== Root exception
+
+The same as xref:#converter-exception[the `exception` converter], but the stack trace is printed starting with the first exception in the causal chain that was thrown followed by each subsequent wrapping exception
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/RootThrowablePatternConverter.html[`RootThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+rEx|rException|rThrowable
+ {
+ ["none" | "short" | "full" | depth]
+ [,filters(package,package,...)]
+ [,separator(separator)]
+ }
+ {ansi(
+ Key=Value,Value,...
+ Key=Value,Value,...
+ ...)
+ }
+ {suffix(pattern)}
+----
+
+The throwable conversion specifier can be followed by an option in the form `%rEx\{short}`, which will only output the first line of the `Throwable`, or `%rEx\{n}`, where the first `n` lines of the stack trace will be printed.
+
+Specifying `%rEx\{none}` or `%rEx\{0}` will suppress printing of the exception.
+
+Use `filters(packages)`, where `packages` is a list of package names to suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace, e.g., `separator(|)`.
+The default value is the `line.separator` system property, which is platform dependent.
+
+Use `rEx{suffix(pattern)}` to add the output of `pattern` to the output only when there is a `Throwable` to print.
+
+[#converter-seq]
+==== Sequence number
+
+Includes a sequence number that will be incremented in every event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/SequenceNumberPatternConverter.html[`SequenceNumberPatternConverter`] specifier grammar
+[source,text]
+----
+sn
+sequenceNumber
+----
+
+The counter is a static variable, so will only be unique within applications that share the same converter class object.
+
+[#converter-style]
+==== Style
+
+Use ANSI escape sequences to style the result of the enclosed pattern.
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/StyleConverter.html[`StyleConverter`] specifier grammar
+[source,text]
+----
+style{pattern}{ANSI style}
+----
+
+The style can consist of a comma-separated list of style names from the following table:
Review Comment:
Fixed in 8950932be4e2865d5fc2cddce84da2b4cb52e940
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1634876354
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
+
+The default colors for each level are:
+
+[%header,cols="1m,1"]
+|===
+|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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`].
+
+The color and attribute names are standard, but the exact shade, hue, or value.
+
+.Color table
+|===
+|Intensity |0 |1 |2 |3 |4 |5 |6 |7
+
+|Normal
+|{set:cellbgcolor:black}Black
+|{set:cellbgcolor:maroon}Red
+|{set:cellbgcolor:green}Green
+|{set:cellbgcolor:olive}Yellow
+|{set:cellbgcolor:navy}Blue
+|{set:cellbgcolor:purple}Magenta
+|{set:cellbgcolor:teal}Cyan
+|{set:cellbgcolor:silver}White
+
+|{set:cellbgcolor:white}Bright
+|{set:cellbgcolor:gray}Black
+|{set:cellbgcolor:red}Red
+|{set:cellbgcolor:lime}Green
+|{set:cellbgcolor:yellow}Yellow
+|{set:cellbgcolor:blue}Blue
+|{set:cellbgcolor:fuchsia}Magenta
+|{set:cellbgcolor:cyan}Cyan
+|{set:cellbgcolor:white}White
+|===
+
+You can use the default colors with:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+----
+
+You can override the default colors in the optional `\{style}` option.
+For example:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+----
+
+You can highlight only the portion of the log event:
+
+[source,text]
+----
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+----
+
+You can style one part of the message and highlight the rest of the log event:
+
+[source,text]
+----
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+----
+
+You can also use the `STYLE` key to use a predefined group of colors:
+
+[source,text]
+----
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+----
+
+The `STYLE` value can be one of:
+
+`Default`:: See above
+`Logback`::
++
+[%header,cols="1m,1"]
+|===
+|Level |ANSI color
+
+|FATAL |Blinking bright red
+
+|ERROR |Bright red
+
+|WARN |Red
+
+|INFO |Blue
+
+|DEBUG |Normal
+
+|TRACE |Normal
+|===
+
+[#converter-level]
+==== Level
+
+Outputs the xref:manual/customloglevels.adoc[level] of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LevelPatternConverter.html[`LevelPatternConverter`] specifier grammar
+[source,text]
+----
+p|level{level=label, level=label, ...}
+p|level{length=n}
+p|level{lowerCase=true|false}
+----
+
+You provide a level name map in the form `level=value, level=value`, where the level is the name of the `Level and value is the value that should be displayed instead of the name of the `Level`.
+For example:
+
+[source,text]
+----
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+----
+
+Alternatively, for the compact-minded:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%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:
+
+[source,text]
+----
+%level{ERROR=Error, length=2}
+----
+
+This gives you the `Error` level name and all other level names of length 2.
+
+Finally, you can output lower-case level names (the default is upper-case):
+
+[source,text]
+----
+%level{lowerCase=true}
+----
+
+[#converter-line]
+==== Line
+
+Outputs the line number from where the log request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LineLocationPatternConverter.html[`LineLocationPatternConverter`] specifier grammar
+[source,text]
+----
+L
+line
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the line number of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-location]
+==== Location
+
+Outputs location information of the caller which generates the logging event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LocationPatternConverter.html[`LocationPatternConverter`] specifier grammar
+[source,text]
+----
+l
+location
+----
+
+The location information depends on the JVM implementation, but it usually consists of the fully qualified name of the calling method followed by the callers' file name and line number.
+
+[WARNING]
+====
+Capturing the source location information of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-logger]
+==== Logger
+
+Outputs the name of the logger that published the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerPatternConverter.html[`LoggerPatternConverter`] specifier grammar
+[source,text]
+----
+c{precision}
+logger{precision}
+----
+
+By default, the layout prints the logger name in full.
+
+A logger conversion specifier can be optionally followed by a _precision specifier_, which consists of a decimal integer, or a pattern starting with a decimal integer.
+
+* 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 the rightmost logger name components.
+If negative, the layout removes the corresponding number of leftmost logger name components.
+* If the precision contains periods then the number before the first period identifies the length to be printed from items that precede tokens in the rest of the pattern.
+If the number after the first period is followed by an asterisk it indicates how many of the rightmost tokens will be printed in full.
+* 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.
Review Comment:
Fixed in 8950932be4e2865d5fc2cddce84da2b4cb52e940
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp the `Layouts` page (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2645:
URL: https://github.com/apache/logging-log4j2/pull/2645#discussion_r1634879820
##########
src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc:
##########
@@ -0,0 +1,1719 @@
+////
+ 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.
+////
+
+= Pattern Layout
+
+Pattern Layout is a customizable, xref:#performance[efficient], xref:#garbage-free[garbage-free], and human-readable string generating layout using a user-provided pattern.
+It is analogous to `String#format()` with specialized directives on injecting certain properties of a `LogEvent`.
+
+[IMPORTANT]
+====
+Pattern Layout is not intended for _structural logging_ purposes.
+For production environments, you are strongly advised to use xref:manual/json-template-layout.adoc[] producing JSON output ready to be delivered to log ingestion systems such as Elasticsearch or Google Cloud Logging.
+====
+
+[#usage]
+== Usage
+
+Pattern Layout is primarily configured using a *conversion pattern* referring to certain properties of a `LogEvent`.
+A conversion pattern is composed of literal text and format control expressions called *conversion specifiers*.
+For instance, given the following layout configuration
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.xml[lines=26..26,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/usage/log4j2.json[lines=6..8,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.yaml[lines=22..23,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/usage/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/usage/log4j2.properties[lines=19..20,indent=0]
+----
+====
+
+then the following statements
+
+[source,java]
+----
+LOGGER.debug("Message 1");
+LOGGER.warn("Message 2");
+----
+
+will yield the output
+
+[source,text]
+----
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+----
+
+Any literal text, including `\t`, `\n`, `\r\`, and `\f` special characters, may be included in the conversion pattern.
+Use `\\` to insert a single backslash into the output.
+
+Each conversion specifier starts with a `%` character, 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, and left and right justification.
+Use `%%` to insert a single `%` into the output.
+Use `%n` to insert the line separator of the platform.
+
+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 log 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 been added to the end of the string.
+To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
+
+[#config]
+== Configuration
+
+This section explains how to configure Pattern Layout plugin element in a Log4j configuration file.
+
+[#plugin-attrs]
+=== Plugin attributes
+
+Pattern Layout plugin configuration accepts the following attributes:
+
+[#plugin-attr-charset]
+==== `charset`
+
+[cols="2h,6"]
+|===
+|Type |`Charset`
+|Default value |The platform default
+|===
+
+`Charset` used for encoding the produced JSON into bytes
+
+[#plugin-attr-pattern]
+==== `pattern`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|Default value |`%m%n`
+|===
+
+A composite pattern string of one or more xref:#converters[].
+`pattern` and xref:#plugin-attr-patternSelector[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-patternSelector]
+==== `patternSelector`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-PatternSelector[`PatternSelector`]
+|===
+
+A component that analyzes information in the `LogEvent` and determines which pattern should be used to format the event.
+`patternSelector` and xref:#plugin-attr-pattern[] are mutually exclusive, that is, only one can be specified.
+
+[#plugin-attr-replace]
+==== `replace`
+
+[cols="2h,6"]
+|===
+|Type |xref:#plugin-element-RegexReplacement[`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.
+
+[#plugin-attr-alwaysWriteExceptions]
+==== `alwaysWriteExceptions`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`true`
+|===
+
+If `true`, 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.
+
+[#plugin-attr-header]
+==== `header`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional header to include at the top of each log file
+
+[#plugin-attr-footer]
+==== `footer`
+
+[cols="2h,6"]
+|===
+|Type |`String`
+|===
+
+The optional footer to include at the bottom of each log file
+
+[#plugin-attr-disableAnsi]
+==== `disableAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true`, do not output ANSI escape codes
+
+[#plugin-attr-noConsoleNoAnsi]
+==== `noConsoleNoAnsi`
+
+[cols="2h,6"]
+|===
+|Type |`boolean`
+|Default value |`false`
+|===
+
+If `true` and `System.console()` is null, do not output ANSI escape codes
+
+[#plugin-elements]
+=== Plugin elements
+
+Pattern Layout plugin configuration accepts the following elements:
+
+[#plugin-element-RegexReplacement]
+==== `RegexReplacement`
+
+Allows portions of the resulting `String` to be replaced.
+This performs a function similar to xref:#converter-RegexReplacement[the `RegexReplacement` converter] but applies to the whole message while the converter only applies to the `String` its pattern generates.
+
+It supports following attributes:
+
+`regex`:: A https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html[Java-compliant regular expression] to match the resulting string
+
+`replacement`:: The string to replace any matched substrings with
+
+[#plugin-element-PatternSelector]
+==== `PatternSelector`
+
+Pattern Layout can be configured with a link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternSelector.html[`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 link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements that identify the various patterns that can be selected.
+
+Predefined ``PatternSelector``s are as follows:
+
+[#plugin-element-LevelPatternSelector]
+===== `LevelPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/LevelPatternSelector.html[`LevelPatternSelector`] selects patterns based on the level of the log event.
+Its configuration is similar to xref:#plugin-element-MarkerPatternSelector[], with the difference that the `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element is matched against the log level associated with the log event.
+
+[#plugin-element-MarkerPatternSelector]
+===== `MarkerPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/MarkerPatternSelector.html[`MarkerPatternSelector`] selects patterns based on the xref:manual/markers.adoc[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 `key` attribute of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] element, then the `pattern` specified on that `PatternMatch` element will be used.
+
+Below is a `MarkerPatternSelector` example switching from the `[%-5level] %c{1.} %msg%n` default pattern to `[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n`, if the marker matches to `FLOW`:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.xml[lines=26..30,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.json[lines=6..16,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.yaml[lines=22..27,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/marker-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/marker-pattern-selector/log4j2.properties[lines=19..24,indent=0]
+----
+====
+
+[#plugin-element-ScriptPatternSelector]
+===== `ScriptPatternSelector`
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/ScriptPatternSelector.html[`ScriptPatternSelector`] selects patterns by matching the output of a xref:manual/scripts.adoc[script] execution against given link:../javadoc/log4j-core/org/apache/logging/log4j/core/layout/PatternMatch.html[`PatternMatch`] elements.
+
+Below is an example using a script determining `NoLocation` or `Flow` keywords from a log event and matching it against two ``PatternMatch``es to configure the effective pattern:
+
+[tabs]
+====
+XML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.xml[`log4j2.xml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.xml[lines=26..40,indent=0]
+----
+
+JSON::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.json[`log4j2.json`]
+[source,json]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.json[lines=6..25,indent=0]
+----
+
+YAML::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.yaml[`log4j2.yaml`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.yaml[lines=22..40,indent=0]
+----
+
+Properties::
++
+.Snippet from an example {antora-examples-url}/manual/pattern-layout/script-pattern-selector/log4j2.properties[`log4j2.properties`]
+[source,xml]
+----
+include::example$manual/pattern-layout/script-pattern-selector/log4j2.properties[lines=19..38,indent=0]
+----
+====
+
+[#converters]
+=== Pattern converters
+
+The Pattern Layout _conversion pattern_ is composed of literal text and format control expressions called _conversion specifiers_ – refer to xref:#usage[] for details.
+xref:manual/plugins.adoc[Plugins] implementing link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/PatternConverter.html[`PatternConverter`] are admitted to the *pattern converter* registry of Pattern Layout, and used to resolve the conversion specifiers.
+The predefined set of pattern converters are shared below.
+
+[#converter-class]
+==== Class
+
+Outputs the fully qualified class name of the caller issuing the logging request
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ClassNamePatternConverter.html[`ClassNamePatternConverter`] specifier grammar
+[source,text]
+----
+C{precision}
+class{precision}
+----
+
+This conversion specifier can be optionally followed by a _precision specifier_ that follows the same rules as xref:#converter-logger[the logger name converter].
+
+[WARNING]
+====
+Capturing the source location information to generate the class name of the caller is an expensive operation, and is not garbage-free.
+xref:#converter-logger[The logger name converter] can generally be used as a zero-cost substitute.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-date]
+==== Date
+
+Outputs the date of the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/DatePatternConverter.html[`DatePatternConverter`] specifier grammar
+[source,text]
+----
+d{pattern}
+date{pattern}
+----
+
+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/8/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+The predefined _named_ formats are:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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/8/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[`java.util.TimeZone#getTimeZone(String)`].
+If no date format specifier is given then the `DEFAULT` format is used.
+
+You can also define custom date formats, see following examples:
+
+[%header,cols="2m,3m"]
+|===
+|Pattern
+|Example output
+
+|%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 1970-01-01 00:00:00 (UTC).
+While the time unit is milliseconds, the granularity depends on the platform.
+This is an efficient way to output the event time because only a conversion from `long` to `String` takes place, there is no `Date` formatting involved.
+
+There is also limited support for timestamps more precise than milliseconds when running on Java 9 or later.
+Note that not all 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 to a millisecond-precision clock when running on Java 9 by setting xref:manual/systemproperties.adoc#log4j2.clock[the `log4j2.clock` system property] to `SystemMillisClock`.
+
+[WARNING]
+====
+Only named date formats (`DEFAULT`, `ISO8601`, `UNIX`, `UNIX_MILLIS`, etc.) are garbage-free.
+====
+
+[#converter-encode]
+==== Encode
+
+Encodes and escapes special characters suitable for output in specific markup languages
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EncodingPatternConverter.html[`EncodingPatternConverter`] specifier grammar
+[source,text]
+----
+enc{pattern}{[HTML|XML|JSON|CRLF]}
+encode{pattern}{[HTML|XML|JSON|CRLF]}
+----
+
+By default, this encodes for HTML if only one option is specified.
+The second option is used to specify which encoding format should be used.
+
+A typical usage would encode the message (i.e., `%enc{%m}`), but the input could come from other locations as well (e.g., from a xref:manual/thread-context.adoc[] entry: `%enc{%mdc\{key}}`).
+
+Using the HTML encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into string literals `\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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`&<>"'`
+|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]:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`U+0000` - `U+001F`
+|`\u0000` - `\u001F`
+
+|Any other control characters
+|Encoded into its `\uABCD` equivalent escaped code point
+
+|`"`
+|`\"`
+
+|`\`
+|`\\`
+|===
+
+[WARNING]
+====
+If you are using JSON encoder in your conversion pattern, it is a strong indicator that you are trying to implement _structured logging_ using Pattern Layout – please, don't!
+*Use xref:manual/json-template-layout.adoc[] instead.*
+====
+
+Using the CRLF encoding format, the following characters are replaced:
+
+[%header,cols="2,4"]
+|===
+|Characters
+|Replacement
+
+|`\r` and `\n`
+|Converted into literal strings `\r` and `\n`, respectively
+|===
+
+[#converter-end-of-batch]
+==== End-of-batch
+
+Outputs the `EndOfBatch` status of the log event as `true` or `false`
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EndOfBatchPatternConverter.html[`EndOfBatchPatternConverter`] specifier grammar
+[source,text]
+----
+endOfBatch
+----
+
+[#converter-equals]
+==== Equals
+
+Replaces occurrences of a string (`test`) with its replacement (`substitution`) in the string resulting from the evaluation of the pattern:
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsReplacementConverter.html[`EqualsReplacementConverter`] and link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/EqualsIgnoreCaseReplacementConverter.html[`EqualsReplacementConverter`] specifiers' grammar
+[source,text]
+----
+equals{pattern}{test}{substitution} +
+equalsIgnoreCase{pattern}{test}{substitution}
+----
+
+For example, `%equals{[%marker]}{[]}\{}` will replace `[]` strings produced by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
+
+[#converter-exception]
+==== Exception
+
+Outputs the `Throwable` attached to the log event
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+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)}
+----
+
+By default this will output the full trace as one would normally find with a call to `Throwable#printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form `%throwable\{option}`.
+
+`%throwable\{short}` outputs the first line of the `Throwable`.
+
+`%throwable{short.className}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable\{n}` outputs the first `n` lines of the stack trace.
+
+Specifying `%throwable\{none}` or `%throwable\{0}` suppresses output of the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of each stack frame.
+
+Use a `{separator(...)}` as the end-of-line string, e.g., `separator(\|)`.
+The default value is the `line.separator` system property, which is operating system dependent.
+
+[WARNING]
+====
+Exception converter is not garbage-free.
+====
+
+[#converter-exception-extended]
+==== Exception (Extended)
+
+The same as xref:#converter-exception[the `%throwable` conversion], but also includes class packaging information
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar
+[source,text]
+----
+xEx|xException|xThrowable
+ { "none"
+ | "full"
+ | depth
+ | "short"
+ | "short.className"
+ | "short.fileName"
+ | "short.lineNumber"
+ | "short.methodName"
+ | "short.message"
+ | "short.localizedMessage"
+ }
+ {filters(package,package,...)}
+ {suffix(pattern)}
+ {separator(separator)}
+----
+
+Different from xref:#converter-exception[the `%throwable` conversion], at the end of each stack element of the exception, a string containing the name of the JAR file that contains the class or the directory the class is located in and the `Implementation-Version` as found in that JAR's manifest will be added.
+If the information is uncertain, then the class packaging data will be preceded by a `~` (tilde) character.
+
+[#converter-file]
+==== File
+
+Outputs the file name where the logging request was issued
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/FileLocationPatternConverter.html[`FileLocationPatternConverter`] specifier grammar
+[source,text]
+----
+F
+file
+----
+
+[WARNING]
+====
+Capturing the source location information to generate the file name of the caller is an expensive operation, and is not garbage-free.
+See xref:manual/layouts.adoc#LocationInformation[this section of the layouts page] for details.
+====
+
+[#converter-fqcn]
+==== FQCN
+
+Outputs the fully qualified class name of the logger
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/LoggerFqcnPatternConverter.html[`LoggerFqcnPatternConverter`] specifier grammar
+[source,text]
+----
+fqcn
+----
+
+[#converter-highlight]
+==== Highlight
+
+Adds ANSI colors to the result of the enclosed pattern based on the current event's xref:manual/customloglevels.adoc[logging level].
+Windows users should refer to xref:#jansi[].
+
+.link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/HighlightConverter.html[`HighlightConverter`] specifier grammar
+[source,text]
+----
+highlight{pattern}{style}
+----
Review Comment:
Fixed in 8950932be4e2865d5fc2cddce84da2b4cb52e940, except for the `DISABLEANSI` and `NOCONSOLEANSI`, which seem more like an internal hack to pass the value of the `PatternLayout` configuration options to the converter, than real options.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org