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: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to