You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ma...@apache.org on 2018/04/09 02:16:11 UTC
[1/3] logging-log4j2 git commit: LOG4J2-1802: Convert layouts manual
page to asciidoc
Repository: logging-log4j2
Updated Branches:
refs/heads/master 59a9c2d4d -> ffd4ab638
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/f8e50945/src/site/xdoc/manual/layouts.xml.vm
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/layouts.xml.vm b/src/site/xdoc/manual/layouts.xml.vm
deleted file mode 100644
index 1340787..0000000
--- a/src/site/xdoc/manual/layouts.xml.vm
+++ /dev/null
@@ -1,2476 +0,0 @@
-<?xml version="1.0"?>
-<!--
- 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.
--->
-
-<document>
- <properties>
- <title>Log4j 2 Layouts</title>
- <author email="rgoers@apache.org">Ralph Goers</author>
- <author email="ggregory@apache.org">Gary Gregory</author>
- </properties>
- #set($dollar = '$')
- #set($sharp = '#')
- #set($javadocRoot = 'http://docs.oracle.com/javase/6/docs/api')
- #macro(javadoc $path $class)
- <a class="javadoc" href="${javadocRoot}/${path}/${class}.html">${class}</a>
- #end
- #set($Charset = "<a class='javadoc' href='${javadocRoot}/java/nio/charset/Charset.html'>Charset</a>")
- #if (!$alignedFileName)
- #set ($isPDF = true)
- #set ($break = '<br />')
- #else
- #set ($isPDF = false)
- #set ($break = '')
- #end
- <body>
- <section name="Layouts">
- <p>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 ${Charset} to
- ensure the byte array contains correct values.
- </p>
- <p>
- The root class for layouts that use a Charset is <code>org.apache.logging.log4j.core.layout.AbstractStringLayout</code>
- where the default is UTF-8. Each layout that extends <code>AbstractStringLayout</code>
- can provide its own default. See each layout below.
- </p>
- <p>
- 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.
- </p>
- <a name="CSVLayouts"/>
- <subsection name="CSV Layouts">
- <p>
- As of Log4j 2.11.0, CSV support has moved from the existing module <code>logj-core</code> to the new module <code>log4j-csv</code>.
- </p>
- <p>
- This layout creates <a href="https://en.wikipedia.org/wiki/Comma-separated_values">Comma Separated Value (CSV)</a>
- records and requires <a href="https://commons.apache.org/proper/commons-csv/">Apache Commons CSV</a> 1.4.
- </p>
- <p>
- The CSV layout can be used in two ways: First, using <code>CsvParameterLayout</code> to log event parameters
- to create a custom database, usually to a logger and file appender uniquely configured for this purpose.
- Second, using <code>CsvLogEventLayout</code> 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.
- </p>
- <p>
- The <code>CsvParameterLayout</code> converts an event's parameters into a CSV record, ignoring the message.
- To log CSV records, you can use the usual Logger methods <code>info()</code>, <code>debug()</code>, and so on:
- </p>
- <pre class="prettyprint linenums">
-logger.info("Ignored", value1, value2, value3);
-</pre>
- <p>
- Which will create the CSV record:
- </p>
- <pre class="prettyprint linenums">
-value1, value2, value3
-</pre>
- <p>
- Alternatively, you can use a <code>ObjectArrayMessage</code>, which only carries parameters:
- </p>
- <pre class="prettyprint linenums">
-logger.info(new ObjectArrayMessage(value1, value2, value3));
-</pre>
- <p>
- The layouts <code>CsvParameterLayout</code> and <code>CsvLogEventLayout</code> are configured with the following parameters:
- </p>
- <table>
- <caption>CsvParameterLayout and CsvLogEventLayout</caption>
- <tr>
- <th>Parameter Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>format</td>
- <td>String</td>
- <td>
- One of the predefined formats: <code>Default</code>, <code>Excel</code>, <code>MySQL</code>,
- <code>RFC4180</code>, <code>TDF</code>.
- See
- <a href="https://commons.apache.org/proper/commons-csv/archives/1.4/apidocs/org/apache/commons/csv/CSVFormat.Predefined.html">CSVFormat.Predefined</a>.
- </td>
- </tr>
- <tr>
- <td>delimiter</td>
- <td>Character</td>
- <td>Sets the delimiter of the format to the specified character.</td>
- </tr>
- <tr>
- <td>escape</td>
- <td>Character</td>
- <td>Sets the escape character of the format to the specified character.</td>
- </tr>
- <tr>
- <td>quote</td>
- <td>Character</td>
- <td>Sets the quoteChar of the format to the specified character.</td>
- </tr>
- <tr>
- <td>quoteMode</td>
- <td>String</td>
- <td>
- Sets the output quote policy of the format to the specified value. One of: <code>ALL</code>,
- <code>MINIMAL</code>, <code>NON_NUMERIC</code>, <code>NONE</code>.
- </td>
- </tr>
- <tr>
- <td>nullString</td>
- <td>String</td>
- <td>Writes null as the given nullString when writing records.</td>
- </tr>
- <tr>
- <td>recordSeparator</td>
- <td>String</td>
- <td>Sets the record separator of the format to the specified String.</td>
- </tr>
- <tr>
- <td>charset</td>
- <td>Charset</td>
- <td>The output Charset.</td>
- </tr>
- <tr>
- <td>header</td>
- <td>Sets the header to include when the stream is opened.</td>
- <td>Desc.</td>
- </tr>
- <tr>
- <td>footer</td>
- <td>Sets the footer to include when the stream is closed.</td>
- <td>Desc.</td>
- </tr>
- </table>
- <p>
- Logging as a CSV events looks like this:
- </p>
- <pre class="prettyprint linenums">
-logger.debug("one={}, two={}, three={}", 1, 2, 3);
-</pre>
- <p>
- Produces a CSV record with the following fields:
- <ol>
- <li>Time Nanos</li>
- <li>Time Millis</li>
- <li>Level</li>
- <li>Thread ID</li>
- <li>Thread Name</li>
- <li>Thread Priority</li>
- <li>Formatted Message</li>
- <li>Logger FQCN</li>
- <li>Logger Name</li>
- <li>Marker</li>
- <li>Thrown Proxy</li>
- <li>Source</li>
- <li>Context Map</li>
- <li>Context Stack</li>
- </ol>
- </p>
- <pre class="prettyprint linenums">
-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),{},[]
-</pre>
- <p>
- Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using CSV layouts.
- </p>
- </subsection>
- <a name="GELFLayout"/>
- <subsection name="GELF Layout">
- <!-- From Javadoc of org.apache.logging.log4j.core.layout.GelfLayout -->
- <p>
- Lays out events in the Graylog Extended Log Format (GELF) 1.1.
- </p>
- <p>
- This layout compresses JSON to GZIP or ZLIB (the <code>compressionType</code>) if log event data is larger than 1024 bytes
- (the <code>compressionThreshold</code>). This layout does not implement chunking.
- </p>
- <p>
- Configure as follows to send to a Graylog 2.x server with UDP:
- </p>
- <pre class="prettyprint linenums">
- <Appenders>
- <Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201">
- <GelfLayout host="someserver" compressionType="ZLIB" compressionThreshold="1024"/>
- </Socket>
- </Appenders>
-</pre>
- <p>
- Configure as follows to send to a Graylog 2.x server with TCP:
- </p>
- <pre class="prettyprint linenums">
- <Appenders>
- <Socket name="Graylog" protocol="tcp" host="graylog.domain.com" port="12201">
- <GelfLayout host="someserver" compressionType="OFF" includeNullDelimiter="true"/>
- </Socket>
- </Appenders>
-</pre>
- <table>
- <tr>
- <th>Parameter Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>host</td>
- <td>String</td>
- <td>The value of the <code>host</code> property (optional, defaults to local host name).</td>
- </tr>
- <tr>
- <td>compressionType</td>
- <td><code>GZIP</code>, <code>ZLIB</code> or <code>OFF</code></td>
- <td>Compression to use (optional, defaults to <code>GZIP</code>)</td>
- </tr>
- <tr>
- <td>compressionThreshold</td>
- <td>int</td>
- <td>Compress if data is larger than this number of bytes (optional, defaults to 1024)</td>
- </tr>
- <tr>
- <td>includeStacktrace</td>
- <td>boolean</td>
- <td>Whether to include full stacktrace of logged Throwables (optional, default to true).
- If set to false, only the class name and message of the #javadoc('java/lang', 'Throwable')
- will be included.</td>
- </tr>
- <tr>
- <td>includeThreadContext</td>
- <td>boolean</td>
- <td>Whether to include thread context as additional fields (optional, default to true).</td>
- </tr>
- <tr>
- <td>includeNullDelimiter</td>
- <td>boolean</td>
- <td>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.</td>
- </tr>
- <caption align="top">GelfLayout Parameters</caption>
- </table>
- <p>
- To include any custom field in the output, use following syntax:
- </p>
- <pre class="prettyprint linenums">
- <GelfLayout>
- <KeyValuePair key="additionalField1" value="constant value"/>
- <KeyValuePair key="additionalField2" value="${dollar}${dollar}{ctx:key}"/>
- </GelfLayout>
-</pre>
- <p>
- Custom fields are included in the order they are declared. The values support <a href="lookups.html">lookups</a>.
- </p>
- <p>
- See also:
- </p>
- <ul>
- <li>The <a href="http://docs.graylog.org/en/latest/pages/gelf.html#gelf">GELF specification</a></li>
- </ul>
- </subsection>
- <a name="HTMLLayout"/>
- <subsection name="HTML Layout">
- <p>The HtmlLayout generates an HTML page and adds each LogEvent to a row in a table.
- </p>
- <table>
- <tr>
- <th>Parameter Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>charset</td>
- <td>String</td>
- <td>The character set to use when converting the HTML String to a byte array. The value must be
- a valid ${Charset}. If not specified, this layout uses UTF-8.</td>
- </tr>
- <tr>
- <td>contentType</td>
- <td>String</td>
- <td>The value to assign to the Content-Type header. The default is "text/html".</td>
- </tr>
- <tr>
- <td>locationInfo</td>
- <td>boolean</td>
- <td>
- <a name="HtmlLocationInfo" />
- <p>If true, the filename and line number will be included in the HTML output. The default value is
- false.</p>
- <p>Generating <a href="#LocationInformation">location information</a>
- is an expensive operation and may impact performance. Use with caution.</p>
- </td>
- </tr>
- <tr>
- <td>title</td>
- <td>String</td>
- <td>A String that will appear as the HTML title.</td>
- </tr>
- <tr>
- <td>fontName</td>
- <td>String</td>
- <td>The <code>font-family</code> to use. The default is "arial,sans-serif".</td>
- </tr>
- <tr>
- <td>fontSize</td>
- <td>String</td>
- <td>The <code>font-size</code> to use. The default is "small".</td>
- </tr>
- <caption align="top">HtmlLayout Parameters</caption>
- </table>
- </subsection>
- <a name="JSONLayout"/>
- <subsection name="JSON Layout">
- <p>
- Appends a series of JSON events as strings serialized as bytes.
- </p>
- <h4>Complete well-formed JSON vs. fragment JSON</h4>
- <p>
- If you configure <code>complete="true"</code>, the appender outputs a well-formed JSON document. By default,
- with <code>complete="false"</code>, you should include the output as an <em>external file</em> in a
- separate file to form a well-formed JSON document.
- </p>
- <p>
- If <code>complete="false"</code>, the appender does not write the JSON open array character "[" at the start
- of the document, "]" and the end, nor comma "," between records.
- </p>
- <p>
- Log event follows this pattern:
- </p>
- <pre class="prettyprint linenums">{
- "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
- }
-}</pre>
- <p>
- If <code>complete="false"</code>, the appender does not write the JSON open array character "[" at the start
- of the document, "]" and the end, nor comma "," between records.
- </p>
- <h4>Pretty vs. compact JSON</h4>
- <p>
- By default, the JSON layout is not compact (a.k.a. not "pretty") with <code>compact="false"</code>, which
- means the appender uses end-of-line characters and indents lines to format the text. If
- <code>compact="true"</code>, then no end-of-line or indentation is used. Message content may contain,
- of course, escaped end-of-lines.
- </p>
- <table>
- <tr>
- <th>Parameter Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>charset</td>
- <td>String</td>
- <td>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.</td>
- </tr>
- <tr>
- <td>compact</td>
- <td>boolean</td>
- <td>If true, the appender does not use end-of-lines and indentation. Defaults to false.</td>
- </tr>
- <tr>
- <td>eventEol</td>
- <td>boolean</td>
- <td>
- 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.
- </td>
- </tr>
- <tr>
- <td>complete</td>
- <td>boolean</td>
- <td>If true, the appender includes the JSON header and footer, and comma between records. Defaults to false.</td>
- </tr>
- <tr>
- <td>properties</td>
- <td>boolean</td>
- <td>If true, the appender includes the thread context map in the generated JSON. Defaults to false.</td>
- </tr>
- <tr>
- <td>propertiesAsList</td>
- <td>boolean</td>
- <td>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.</td>
- </tr>
- <tr>
- <td>locationInfo</td>
- <td>boolean</td>
- <td>
- <p>If true, the appender includes the location information in the generated JSON. Defaults to false.</p>
- <p>Generating <a href="#LocationInformation">location information</a>
- is an expensive operation and may impact performance. Use with caution.</p>
- </td>
- </tr>
- <tr>
- <td>includeStacktrace</td>
- <td>boolean</td>
- <td>If true, include full stacktrace of any logged #javadoc('java/lang', 'Throwable') (optional, default to true).</td>
- </tr>
- <tr>
- <td>stacktraceAsString</td>
- <td>boolean</td>
- <td>Whether to format the stacktrace as a string, and not a nested object (optional, defaults to false).</td>
- </tr>
- <tr>
- <td>includeNullDelimiter</td>
- <td>boolean</td>
- <td>Whether to include NULL byte as delimiter after each event (optional, default to false).</td>
- </tr>
- <tr>
- <td>objectMessageAsJsonObject</td>
- <td>boolean</td>
- <td>If true, ObjectMessage is serialized as JSON object to the "message" field of the output log. Defaults to false.</td>
- </tr>
- <caption align="top">JsonLayout Parameters</caption>
- </table>
- <p>
- To include any custom field in the output, use following syntax:
- </p>
- <pre class="prettyprint linenums">
- <JsonLayout>
- <KeyValuePair key="additionalField1" value="constant value"/>
- <KeyValuePair key="additionalField2" value="${dollar}${dollar}{ctx:key}"/>
- </JsonLayout>
-</pre>
- <p>
- Custom fields are always last, in the order they are declared. The values support <a href="lookups.html">lookups</a>.
- </p>
- <p>
- Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using JsonLayout.
- </p>
- </subsection>
- <a name="PatternLayout"/>
- <subsection name="Pattern Layout">
- <p>A flexible layout configurable with pattern string. The goal of this class is to format a LogEvent and
- return the results. The format of the result depends on the <em>conversion pattern</em>.
- </p>
- <p>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
- <em>conversion specifiers</em>.
- </p>
- <p><i>Note that any literal text, including <b>Special Characters</b>, may be included in the conversion
- pattern.</i> Special Characters include <b>\t</b>, <b>\n</b>, <b>\r</b>, <b>\f</b>. Use <b>\\</b> to
- insert a single backslash into the output.
- </p>
- <p>Each conversion specifier starts with a percent sign (%) and is followed by optional <em>format
- modifiers</em> and a <em>conversion character</em>. The conversion character specifies the type of
- data, e.g. category, priority, date, thread name. The format modifiers control such things as field width,
- padding, left and right justification. The following is a simple example.
- </p>
- <p>Let the conversion pattern be <b>"%-5p [%t]: %m%n"</b> and assume that the Log4j environment was set to
- use a PatternLayout. Then the statements
- <pre>Logger logger = LogManager.getLogger("MyLogger");
-logger.debug("Message 1");
-logger.warn("Message 2");</pre>
- would yield the output
- <pre>DEBUG [main]: Message 1
-WARN [main]: Message 2</pre>
- </p>
- <p>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 <b>%-5p</b> means the priority of the logging event should
- be left justified to a width of five characters.
- </p>
- <p>
- If the pattern string does not contain a specifier to handle a Throwable being logged, parsing of the
- pattern will act as if the "%xEx" specifier had be added to the end of the string. To suppress
- formatting of the Throwable completely simply add "%ex{0}" as a specifier in the pattern string.
- </p>
- <table>
- <tr>
- <th>Parameter Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>charset</td>
- <td>String</td>
- <td>The character set to use when converting the syslog String to a byte array. The String must be
- a valid ${Charset}. If not specified, this layout uses the platform default character set.
- </td>
- </tr>
- <tr>
- <td>pattern</td>
- <td>String</td>
- <td>A composite pattern string of one or more conversion patterns from the table below. Cannot be
- specified with a PatternSelector.</td>
- </tr>
- <tr>
- <td>patternSelector</td>
- <td>PatternSelector</td>
- <td>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.</td>
- </tr>
- <tr>
- <td>replace</td>
- <td>RegexReplacement</td>
- <td>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.
- </td>
- </tr>
- <tr>
- <td>alwaysWriteExceptions</td>
- <td>boolean</td>
- <td>If <code>true</code> (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
- <code>false</code> disables this behavior and allows you to exclude exceptions from your pattern
- output.</td>
- </tr>
- <tr>
- <td>header</td>
- <td>String</td>
- <td>The optional header string to include at the top of each log file.</td>
- </tr>
- <tr>
- <td>footer</td>
- <td>String</td>
- <td>The optional footer string to include at the bottom of each log file.</td>
- </tr>
- <tr>
- <td>disableAnsi</td>
- <td>boolean</td>
- <td>If <code>true</code> (default is false), do not output ANSI escape codes.</td>
- </tr>
- <tr>
- <td>noConsoleNoAnsi</td>
- <td>boolean</td>
- <td>If <code>true</code> (default is false) and <code>System.console()</code> is null, do not output ANSI escape codes.</td>
- </tr>
- <caption align="top">PatternLayout Parameters</caption>
- </table>
- <table>
- <tr>
- <th>Parameter Name</th>
- <th>Type</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>regex</td>
- <td>String</td>
- <td>A Java-compliant regular expression to match in the resulting string. See
- #javadoc('java/util/regex', 'Pattern').</td>
- </tr>
- <tr>
- <td>replacement</td>
- <td>String</td>
- <td>The string to replace any matched sub-strings with.</td>
- </tr>
- <caption align="top">RegexReplacement Parameters</caption>
- </table>
- <h4>Patterns</h4>
- <p>The conversions that are provided with Log4j are:
- </p>
- <table>
- <tr>
- <th>Conversion Pattern</th>
- <th>Description</th>
- </tr>
- <tr>
- <td align="center">
- <b>c</b>{precision}<br />
- <b>logger</b>{precision}
- </td>
- <td>
- <p>Outputs the name of the logger that published the logging event. The logger conversion
- specifier can be optionally followed by <em>precision specifier</em>, which consists of a
- decimal integer, or a pattern starting with a decimal integer.
- </p>
- <p>When the precision specifier is an integer value, it reduces the size of the logger name.
- If the number is positive, the layout prints the corresponding number of rightmost logger
- name components. If negative, the layout removes the corresponding number of leftmost logger
- name components.
- </p>
- <p>
- 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.
- </p>
- <table>
- <tr>
- <th>Conversion Pattern</th>
- <th>Logger Name</th>
- <th>Result</th>
- </tr>
- <tr>
- <td>%c{1}</td>
- <td>org.apache.${break}commons.Foo</td>
- <td>Foo</td>
- </tr>
- <tr>
- <td>%c{2}</td>
- <td>org.apache.${break}commons.Foo</td>
- <td>commons.Foo</td>
- </tr>
- <tr>
- <td>%c{10}</td>
- <td>org.apache.${break}commons.Foo</td>
- <td>org.apache.${break}commons.Foo</td>
- </tr>
- <tr>
- <td>%c{-1}</td>
- <td>org.apache.${break}commons.Foo</td>
- <td>apache.${break}commons.Foo</td>
- </tr>
- <tr>
- <td>%c{-2}</td>
- <td>org.apache.${break}commons.Foo</td>
- <td>${break}commons.Foo</td>
- </tr>
- <tr>
- <td>%c{-10}</td>
- <td>org.apache.${break}commons.Foo</td>
- <td>org.apache.${break}commons.Foo</td>
- </tr>
- <tr>
- <td>%c{1.}</td>
- <td>org.apache.${break}commons.Foo</td>
- <td>o.a.c.Foo</td>
- </tr>
- <tr>
- <td>%c{1.1.~.~}</td>
- <td>org.apache.${break}commons.test.${break}Foo</td>
- <td>o.a.~.~.Foo</td>
- </tr>
- <tr>
- <td>%c{.}</td>
- <td>org.apache.${break}commons.test.${break}Foo</td>
- <td>....Foo</td>
- </tr>
- </table>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternClass" />
- <b>C</b>{precision}<br />
- <b>class</b>{precision}
- </td>
- <td>
- <p>Outputs the fully qualified class name of the caller issuing the logging request.
- This conversion specifier can be optionally followed by <em>precision specifier</em>, that
- follows the same rules as the logger name converter.
- </p>
- <p>Generating the class name of the caller (<a href="#LocationInformation">location information</a>)
- is an expensive operation and may impact performance. Use with caution.</p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <b>d</b>{pattern}<br />
- <b>date</b>{pattern}
- </td>
- <td>
- <p>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
- #javadoc('java/text', 'SimpleDateFormat').
- </p>
- <p>The predefined formats are
- <code>DEFAULT</code>,
- <code>ABSOLUTE</code>,
- <code>COMPACT</code>,
- <code>DATE</code>,
- <code>ISO8601</code>,
- and
- <code>ISO8601_BASIC</code>.
- </p>
- <p>You can also use a set of braces containing a time zone id per
- <a class="javadoc" href="${javadocRoot}/java/util/TimeZone.html${sharp}getTimeZone(java.lang.String)">
- java.util.TimeZone.getTimeZone</a>. If no date format specifier is given then the DEFAULT format is used.
- <table>
- <tr>
- <th>Pattern</th>
- <th>Example</th>
- </tr>
- <tr>
- <td>%d{DEFAULT}</td>
- <td>2012-11-02 14:34:02,123</td>
- </tr>
- <tr>
- <td>%d{DEFAULT_MICROS}</td>
- <td>2012-11-02 14:34:02,123456</td>
- </tr>
- <tr>
- <td>%d{DEFAULT_NANOS}</td>
- <td>2012-11-02 14:34:02,123456789</td>
- </tr>
- <tr>
- <td>%d{ISO8601}</td>
- <td>2012-11-02T14:34:02,781</td>
- </tr>
- <tr>
- <td>%d{ISO8601_BASIC}</td>
- <td>20121102T143402,781</td>
- </tr>
- <tr>
- <td>%d{ABSOLUTE}</td>
- <td>14:34:02,781</td>
- </tr>
- <tr>
- <td>%d{ABSOLUTE_MICROS}</td>
- <td>14:34:02,123456</td>
- </tr>
- <tr>
- <td>%d{ABSOLUTE_NANOS}</td>
- <td>14:34:02,123456789</td>
- </tr>
- <tr>
- <td>%d{DATE}</td>
- <td>02 Nov 2012 14:34:02,781</td>
- </tr>
- <tr>
- <td>%d{COMPACT}</td>
- <td>20121102143402781</td>
- </tr>
- <tr>
- <td>%d{HH:mm:ss,SSS}</td>
- <td>14:34:02,123</td>
- </tr>
- <tr>
- <td>%d{HH:mm:ss,nnnn} to %d{HH:mm:ss,nnnnnnnnn}</td>
- <td>14:34:02,1234 to 14:34:02,123456789</td>
- </tr>
- <tr>
- <td>%d{dd MMM yyyy HH:mm:ss,SSS}</td>
- <td>02 Nov 2012 14:34:02,123</td>
- </tr>
- <tr>
- <td>%d{dd MMM yyyy HH:mm:ss,nnnn} to %d{dd MMM yyyy HH:mm:ss,nnnnnnnnn}</td>
- <td>02 Nov 2012 14:34:02,1234 to 02 Nov 2012 14:34:02,123456789</td>
- </tr>
- <tr>
- <td>%d{HH:mm:ss}{GMT+0}</td>
- <td>18:34:02</td>
- </tr>
- <tr>
- <td>%d{UNIX}</td>
- <td>1351866842</td>
- </tr>
- <tr>
- <td>%d{UNIX_MILLIS}</td>
- <td>1351866842781</td>
- </tr>
- </table>
- </p>
- <p>
- %d{UNIX} outputs the UNIX time in seconds. %d{UNIX_MILLIS} outputs the UNIX time in milliseconds.
- The UNIX time is the difference, in seconds for UNIX and in milliseconds for UNIX_MILLIS, between
- the current time and midnight, January 1, 1970 UTC. While the time unit is milliseconds, the
- granularity depends on the operating system
- (<a href="http://msdn.microsoft.com/en-us/windows/hardware/gg463266.aspx">Windows</a>).
- 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.
- </p>
- <p>
- Log4j 2.11 adds limited support for timestamps more precise than milliseconds when running on Java 9.
- Note that not all
- <a href="https://docs.oracle.com/javase/9/docs/api/java/time/format/DateTimeFormatter.html">DateTimeFormatter</a>
- formats are supported.
- Only timestamps in the formats mentioned in the table above may use the "nano-of-second"
- pattern letter <code>n</code> instead of the "fraction-of-second" pattern letter <code>S</code>.
- </p>
- <p>
- Users may revert back to a millisecond-precision clock when running on Java 9 by setting system property
- <code>log4j2.Clock</code> to <code>SystemMillisClock</code>.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <b>enc</b>{<i>pattern</i>}{[HTML|XML|JSON|CRLF]}<br />
- <b>encode</b>{<i>pattern</i>}{[HTML|XML|JSON|CRLF]}
- </td>
- <td>
- <p>
- 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.
- </p>
- <p>
- A typical usage would encode the message
- <code>%enc{%m}</code>
- but user input could come from other locations as well, such as the MDC
- <code>%enc{%mdc{key}}</code>
- </p>
- <p>Using the HTML encoding format, the following characters are replaced:</p>
- <table>
- <tr>
- <th>Character</th>
- <th>Replacement</th>
- </tr>
- <tr>
- <td>'\r', '\n'</td>
- <td>Converted into escaped strings "\\r" and "\\n" respectively</td>
- </tr>
- <tr>
- <td>&, <, >, ", ', /</td>
- <td>Replaced with the corresponding HTML entity</td>
- </tr>
- </table>
- <p>Using the XML encoding format, this follows the escaping rules specified by
- <a href="https://www.w3.org/TR/xml/">the XML specification</a>:</p>
- <table>
- <tr>
- <th>Character</th>
- <th>Replacement</th>
- </tr>
- <tr>
- <td>&, <, >, ", '</td>
- <td>Replaced with the corresponding XML entity</td>
- </tr>
- </table>
- <p>
- Using the JSON encoding format, this follows the escaping rules specified by
- <a href="https://www.ietf.org/rfc/rfc4627.txt">RFC 4627 section 2.5</a>:
- </p>
- <table>
- <tr>
- <th>Character</th>
- <th>Replacement</th>
- </tr>
- <tr>
- <td>U+0000 - U+001F</td>
- <td>\u0000 - \u001F</td>
- </tr>
- <tr>
- <td>Any other control characters</td>
- <td>Encoded into its <code>\uABCD</code> equivalent escaped code point</td>
- </tr>
- <tr>
- <td>"</td>
- <td>\"</td>
- </tr>
- <tr>
- <td>\</td>
- <td>\\</td>
- </tr>
- </table>
- <p>
- For example, the pattern <code>{"message": "%enc{%m}{JSON}"}</code> could be used to output a
- valid JSON document containing the log message as a string value.
- </p>
- <p>Using the CRLF encoding format, the following characters are replaced:</p>
- <table>
- <tr>
- <th>Character</th>
- <th>Replacement</th>
- </tr>
- <tr>
- <td>'\r', '\n'</td>
- <td>Converted into escaped strings "\\r" and "\\n" respectively</td>
- </tr>
- </table>
- </td>
- </tr>
- <tr>
- <td align="center">
- <b>equals</b>{pattern}{test}{substitution}<br />
- <b>equalsIgnoreCase</b>{pattern}{test}{substitution}
- </td>
- <td>
- <p>Replaces occurrences of 'test', a string, with its replacement 'substitution' in the
- string resulting from evaluation of the pattern. For example, "%equals{[%marker]}{[]}{}" will
- replace '[]' strings produces by events without markers with an empty string.
- </p>
- <p>The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <b>ex</b>|<b>exception</b>|<b>throwable</b><br/>
- {<br/>
- [ "none"<br />
- | "full"<br />
- | depth<br />
- | "short"<br />
- | "short.className"<br />
- | "short.fileName"<br />
- | "short.lineNumber"<br />
- | "short.methodName"<br />
- | "short.message"<br />
- | "short.localizedMessage"]<br />
- }<br />
- {filters(package,package,...)}<br/>
- {suffix(<i>pattern</i>)}<br/>
- {separator(<i>separator</i>)}<br/>
- </td>
- <td>
- <p>
- 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 <code>Throwable.printStackTrace()</code>.
- </p>
- <p>
- You can follow the throwable conversion word with an option in the form <code>%throwable{option}</code>.
- </p>
- <p>
- <code>%throwable{short}</code> outputs the first line of the Throwable.
- </p>
- <p>
- <code>%throwable{short.className}</code> outputs the name of the class where the exception occurred.
- </p>
- <p>
- <code>%throwable{short.methodName}</code> outputs the method name where the exception occurred.
- </p>
- <p>
- <code>%throwable{short.fileName}</code> outputs the name of the class where the exception occurred.
- </p>
- <p>
- <code>%throwable{short.lineNumber}</code> outputs the line number where the exception occurred.
- </p>
- <p>
- <code>%throwable{short.message}</code> outputs the message.
- </p>
- <p>
- <code>%throwable{short.localizedMessage}</code> outputs the localized message.
- </p>
- <p>
- <code>%throwable{n}</code> outputs the first n lines of the stack trace.
- </p>
- <p>
- Specifying <code>%throwable{none}</code> or <code>%throwable{0}</code> suppresses output of the exception.
- </p>
- <p>
- Use <code>{filters(<i>packages</i>)}</code> where <i>packages</i> is a list of package names to
- suppress matching stack frames from stack traces.
- </p>
- <p>
- Use <code>{suffix(<i>pattern</i>)}</code> to add the output of <i>pattern</i> at the end of each stack frames.
- </p>
- <p>
- Use a <code>{separator(...)}</code> as the end-of-line string. For example: <code>separator(|)</code>.
- The default value is the <code>line.separator</code> system property, which is operating system dependent.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternFile" />
- <b>F</b><br />
- <b>file</b>
- </td>
- <td><p>Outputs the file name where the logging request was issued.</p>
- <p>Generating the file information (<a href="#LocationInformation">location information</a>)
- is an expensive operation and may impact performance. Use with caution.</p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <b>highlight</b>{pattern}{style}
- </td>
- <td>
- <p>Adds ANSI colors to the result of the enclosed pattern based on the current event's logging level.
- (See Jansi <a href="#enable-jansi">configuration</a>.)
- </p>
- <p>The default colors for each level are:
- <table>
- <tr>
- <th>Level</th>
- <th>ANSI color</th>
- </tr>
- <tr>
- <td>FATAL</td>
- <td>Bright red</td>
- </tr>
- <tr>
- <td>ERROR</td>
- <td>Bright red</td>
- </tr>
- <tr>
- <td>WARN</td>
- <td>Yellow</td>
- </tr>
- <tr>
- <td>INFO</td>
- <td>Green</td>
- </tr>
- <tr>
- <td>DEBUG</td>
- <td>Cyan</td>
- </tr>
- <tr>
- <td>TRACE</td>
- <td>Black (looks dark grey)</td>
- </tr>
- </table>
- </p>
- <p>The color names are ANSI names defined in the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/pattern/AnsiEscape.html">AnsiEscape</a> class.
- </p>
- <p>The color and attribute names and are standard, but the exact shade, hue, or value.
- </p>
- <table>
- <caption>Color table</caption>
- <tbody>
- <tr>
- <th>Intensity Code</th>
- <th>0</th>
- <th>1</th>
- <th>2</th>
- <th>3</th>
- <th>4</th>
- <th>5</th>
- <th>6</th>
- <th>7</th>
- </tr>
- <tr>
- <th>Normal</th>
- <td style="background: black;color:white">Black</td>
- <td style="background: maroon;color:white">Red</td>
- <td style="background: green;color:white">Green</td>
- <td style="background: olive;color:white">Yellow</td>
- <td style="background: navy;color:white">Blue</td>
- <td style="background: purple;color:white">Magenta</td>
- <td style="background: teal;color:white">Cyan</td>
- <td style="background: silver;color:black">White</td>
- </tr>
- <tr>
- <th>Bright</th>
- <td style="background: gray;color:white">Black</td>
- <td style="background: red;color:black">Red</td>
- <td style="background: lime;color:black">Green</td>
- <td style="background: yellow;color:black">Yellow</td>
- <td style="background: blue;color:white">Blue</td>
- <td style="background: fuchsia;color:black">Magenta</td>
- <td style="background: cyan;color:black">Cyan</td>
- <td style="background: white;color:black">White</td>
- </tr>
- </tbody>
- </table>
- <p>You can use the default colors with:
- <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}</pre>
- </p>
- <p>You can override the default colors in the optional {style} option. For example:
- #if ($isPDF)
- <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}
- {FATAL=white, ERROR=red, WARN=blue, INFO=black,
- DEBUG=green, TRACE=blue}</pre>
- #else
- <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}</pre>
- #end
- </p>
- <p>You can highlight only the a portion of the log event:
- <pre>%d [%t] %highlight{%-5level: %msg%n%throwable}</pre>
- </p>
- <p>You can style one part of the message and highlight the rest the log event:
- #if ($isPDF)
- <pre>%style{%d [%t]}{black} %highlight{%-5level:
- %msg%n%throwable}</pre>
- #else
- <pre>%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}</pre>
- #end
- </p>
- #if ($isPDF)
- <!--PB-->
- #end
- <p>You can also use the STYLE key to use a predefined group of colors:
- #if ($isPDF)
- <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}
- {STYLE=Logback}</pre>
- #else
- <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}</pre>
- #end
- The STYLE value can be one of:
- <table>
- <?dbfo keep-together="auto" ?>
- <tr>
- <th>Style</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>Default</td>
- <td>See above</td>
- </tr>
- <tr>
- <td>Logback</td>
- <td>
- <table>
- <tr>
- <th>Level</th>
- <th>ANSI color</th>
- </tr>
- <tr>
- <td>FATAL</td>
- <td>Blinking bright red</td>
- </tr>
- <tr>
- <td>ERROR</td>
- <td>Bright red</td>
- </tr>
- <tr>
- <td>WARN</td>
- <td>Red</td>
- </tr>
- <tr>
- <td>INFO</td>
- <td>Blue</td>
- </tr>
- <tr>
- <td>DEBUG</td>
- <td>Normal</td>
- </tr>
- <tr>
- <td>TRACE</td>
- <td>Normal</td>
- </tr>
- </table>
- </td>
- </tr>
- </table>
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternMap"/>
- <b>K</b>{key}<br />
- <b>map</b>{key}<br />
- <b>MAP</b>{key}
- </td>
- <td>
- <p>Outputs the entries in a
- <a class="javadoc" href="../log4j-api/apidocs/org/apache/logging/log4j/message/MapMessage.html">MapMessage</a>,
- if one is present in the event. The <b>K</b> conversion character can be followed by the key
- for the map placed between braces, as in
- <b>%K{clientNumber}</b> where <code>clientNumber</code> is the key. The value in the Map
- corresponding to the key will be output. If no additional sub-option
- is specified, then the entire contents of the Map key value pair set
- is output using a format {{key1,val1},{key2,val2}}
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternLocation" />
- <b>l</b><br />
- <b>location</b>
- </td>
- <td>
- <p>Outputs location information of the caller which generated the logging event.
- </p>
- <p>The location information depends on the JVM implementation but usually consists of the fully
- qualified name of the calling method followed by the callers source the file name and line
- number between parentheses.
- </p>
- <p>Generating <a href="#LocationInformation">location information</a>
- is an expensive operation and may impact performance. Use with caution.</p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternLine" />
- <b>L</b><br />
- <b>line</b>
- </td>
- <td><p>Outputs the line number from where the logging request
- was issued.</p>
- <p>Generating line number information (<a href="#LocationInformation">location information</a>)
- is an expensive operation and may impact performance. Use with caution.</p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternMessage"/>
- <b>m</b>{nolookups}{ansi}<br />
- <b>msg</b>{nolookups}{ansi}<br />
- <b>message</b>{nolookups}{ansi}
- </td>
- <td>
- <p>
- Outputs the application supplied message associated with the logging event.
- </p>
- <!-- Copied and tweaked from Javadoc for org.apache.logging.log4j.core.pattern.JAnsiMessageRenderer -->
- <p>
- Add <code>{ansi}</code> to render messages with ANSI escape codes (requires JAnsi,
- see <a href="#enable-jansi">configuration</a>.)
- </p>
- <p>
- The default syntax for embedded ANSI codes is:
- </p>
- <pre class="prettyprint linenums">@|<em>code</em>(,<em>code</em>)* <em>text</em>|@</pre>
- <p>
- For example, to render the message <code>"Hello"</code> in green, use:
- </p>
- <pre class="prettyprint linenums">@|green Hello|@</pre>
- <p>
- To render the message <code>"Hello"</code> in bold and red, use:
- </p>
- <pre class="prettyprint linenums">@|bold,red Warning!|@</pre>
- <p>
- You can also define custom style names in the configuration with the syntax:
- </p>
- <pre class="prettyprint linenums">%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n</pre>
- <p>
- For example:
- </p>
- <pre class="prettyprint linenums">%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n</pre>
- <p>
- The call site can look like this:
- </p>
- <pre class="prettyprint linenums">logger.info("@|KeyStyle {}|@ = @|ValueStyle {}|@", entry.getKey(), entry.getValue());</pre>
- <p>
- Use <code>{nolookups}</code> to log messages like <code>"${esc.d}{date:YYYY-MM-dd}"</code>
- without using any lookups. Normally calling <code>logger.info("Try ${esc.d}{date:YYYY-MM-dd}")</code>
- would replace the date template <code>${esc.d}{date:YYYY-MM-dd}</code> with an actual date.
- Using <code>nolookups</code> disables this feature and logs the message string untouched.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternMethod" />
- <b>M</b><br />
- <b>method</b>
- </td>
- <td><p>Outputs the method name where the logging request was issued.</p>
- <p>Generating the method name of the caller (<a href="#LocationInformation">location information</a>)
- is an expensive operation and may impact performance. Use with caution.</p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternMarker"/>
- <b>marker</b>
- </td>
- <td>The full name of the marker, including parents, if one is present.</td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternMarkerSimpleName"/>
- <b>markerSimpleName</b>
- </td>
- <td>The simple name of the marker (not including parents), if one is present.</td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternMaxLength"/>
- <b>maxLen</b><br/>
- <b>maxLength</b>
- </td>
- <td>
- <p>
- 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.
- </p>
- <p>
- Example syntax: <code>%maxLen{%p: %c{1} - %m%notEmpty{ =>%ex{short}}}{160}</code> will be limited to
- 160 characters with a trailing ellipsis. Another example: <code>%maxLen{%m}{20}</code> will be
- limited to 20 characters and no trailing ellipsis.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternNewLine"/>
- <b>n</b>
- </td>
- <td>
- <p>Outputs the platform dependent line separator character or characters.
- </p>
- <p>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.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="NanoTime" />
- <b>N</b><br />
- <b>nano</b>
- </td>
- <td><p>Outputs the result of <code>System.nanoTime()</code> at the time the log event was created.</p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="Process ID" />
- <b>pid</b>{[defaultValue]}<br />
- <b>processId</b>{[defaultValue]}
- </td>
- <td><p>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.</p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="VariablesNotEmpty" />
- <b>variablesNotEmpty</b>{pattern}<br />
- <b>varsNotEmpty</b>{pattern}<br />
- <b>notEmpty</b>{pattern}
- </td>
- <td>
- <p>
- Outputs the result of evaluating the pattern if and only if all variables in the pattern are not empty.
- </p>
- <p>
- For example:
- <pre>%notEmpty{[%marker]}</pre>
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternLevel"/>
- <b>p</b>|<b>level</b>{<em>level</em>=<em>label</em>, <em>level</em>=<em>label</em>, ...}
- <b>p</b>|<b>level</b>{length=<em>n</em>}
- <b>p</b>|<b>level</b>{lowerCase=<em>true</em>|<em>false</em>}
- </td>
- <td>
- <p>
- Outputs the level of the logging event. You provide a level name map in the form
- "level=value, level=value" where level is the name of the Level and value is the value that
- should be displayed instead of the name of the Level.
- </p>
- <p>
- For example:
- <pre>%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}</pre>
- </p>
- <p>
- Alternatively, for the compact-minded:
- <pre>%level{WARN=W, DEBUG=D, ERROR=E, TRACE=T, INFO=I}</pre>
- </p>
- <p>
- More succinctly, for the same result as above, you can define the length of the level label:
- <pre>%level{length=1}</pre>
- If the length is greater than a level name length, the layout uses the normal level name.
- </p>
- <p>
- You can combine the two kinds of options:
- <pre>%level{ERROR=Error, length=2}</pre>
- This give you the <code>Error</code> level name and all other level names of length 2.
- </p>
- <p>
- Finally, you can output lower-case level names (the default is upper-case):
- <pre>%level{lowerCase=true}</pre>
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternRelative"/>
- <b>r</b><br />
- <b>relative</b>
- </td>
- <td>Outputs the number of milliseconds elapsed since the JVM was started until the creation
- of the logging event.
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternReplace"/>
- <b>replace</b>{pattern}{regex}{substitution}
- </td>
- <td>
- <p>Replaces occurrences of 'regex', a regular expression, with its replacement 'substitution' in the
- string resulting from evaluation of the pattern. For example, "%replace{%msg}{\s}{}" will remove
- all spaces contained in the event message.
- </p>
- <p>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.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternException"/>
- <b>rEx</b>|<b>rException</b>|<b>rThrowable</b><br/>
- {<br/>
- ["none" | "short" | "full" | depth]<br/>
- [,filters(package,package,...)]<br/>
- [,separator(<i>separator</i>)]<br/>
- }<br/>
- {ansi(<br/>
- Key=Value,Value,...<br/>
- Key=Value,Value,...<br/>
- ...)<br/>
- }<br/>
- {suffix(<i>pattern</i>)}<br/>
- </td>
- <td>
- <p>
- 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.
- </p>
- <p>
- The throwable conversion word can be followed by an option in the form
- <code>%rEx{short}</code> which will only output the first line of the Throwable or
- <code>%rEx{n}</code> where the first n lines of the stack trace will be printed.
- </p>
- <p>
- Specifying <code>%rEx{none}</code> or <code>%rEx{0}</code> will suppress printing of the exception.
- </p>
- <p>
- Use <code>filters(<i>packages</i>)</code> where <i>packages</i> is a list of package names to
- suppress matching stack frames from stack traces.
- </p>
- <p>
- Use a <code>separator</code> string to separate the lines of a stack trace. For example:
- <code>separator(|)</code>. The default value is the <code>line.separator</code> system property,
- which is operating system dependent.
- </p>
- <p>
- Use <code>rEx{suffix(<i>pattern</i>)</code> to add the output of <i>pattern</i> to the output only
- when there is a throwable to print.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternSequenceNumber"/>
- <b>sn</b><br />
- <b>sequenceNumber</b>
- </td>
- <td>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.</td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternStyle"/>
- <b>style</b>{pattern}{ANSI style}
- </td>
- <td>
- <p>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 <a href="#enable-jansi">configuration</a>.)
- <table>
- <tr>
- <th>Style Name</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>Normal</td>
- <td>Normal display</td>
- </tr>
- <tr>
- <td>Bright</td>
- <td>Bold</td>
- </tr>
- <tr>
- <td>Dim</td>
- <td>Dimmed or faint characters</td>
- </tr>
- <tr>
- <td>Underline</td>
- <td>Underlined characters</td>
- </tr>
- <tr>
- <td>Blink</td>
- <td>Blinking characters</td>
- </tr>
- <tr>
- <td>Reverse</td>
- <td>Reverse video</td>
- </tr>
- <tr>
- <td>Hidden</td>
- <td></td>
- </tr>
- <tr>
- <td>Black or FG_Black</td>
- <td>Set foreground color to black</td>
- </tr>
- <tr>
- <td>Red or FG_Red</td>
- <td>Set foreground color to red</td>
- </tr>
- <tr>
- <td>Green or FG_Green</td>
- <td>Set foreground color to green</td>
- </tr>
- <tr>
- <td>Yellow or FG_Yellow</td>
- <td>Set foreground color to yellow</td>
- </tr>
- <tr>
- <td>Blue or FG_Blue</td>
- <td>Set foreground color to blue</td>
- </tr>
- <tr>
- <td>Magenta or FG_Magenta</td>
- <td>Set foreground color to magenta</td>
- </tr>
- <tr>
- <td>Cyan or FG_Cyan</td>
- <td>Set foreground color to cyan</td>
- </tr>
- <tr>
- <td>White or FG_White</td>
- <td>Set foreground color to white</td>
- </tr>
- <tr>
- <td>Default or FG_Default</td>
- <td>Set foreground color to default (white)</td>
- </tr>
- <tr>
- <td>BG_Black</td>
- <td>Set background color to black</td>
- </tr>
- <tr>
- <td>BG_Red</td>
- <td>Set background color to red</td>
- </tr>
- <tr>
- <td>BG_Green</td>
- <td>Set background color to green</td>
- </tr>
- <tr>
- <td>BG_Yellow</td>
- <td>Set background color to yellow</td>
- </tr>
- <tr>
- <td>BG_Blue</td>
- <td>Set background color to blue</td>
- </tr>
- <tr>
- <td>BG_Magenta</td>
- <td>Set background color to magenta</td>
- </tr>
- <tr>
- <td>BG_Cyan</td>
- <td>Set background color to cyan</td>
- </tr>
- <tr>
- <td>BG_White</td>
- <td>Set background color to white</td>
- </tr>
- </table>
- </p>
- <p>For example:
- <pre>%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}</pre>
- </p>
- <p>You can also combine styles:
- <pre>%d %highlight{%p} %style{%logger}{bright,cyan} %C{1.} %msg%n</pre>
- </p>
- <p>You can also use <code>%</code> with a color like <code>%black</code>, <code>%blue</code>, <code>%cyan</code>, and so on. For example:
- <pre>%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}</pre>
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternThreadId"/>
- <b>T</b><br />
- <b>tid</b><br />
- <b>threadId</b>
- </td>
- <td>Outputs the ID of the thread that generated the logging event.</td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternThreadName"/>
- <b>t</b><br />
- <b>tn</b><br />
- <b>thread</b><br />
- <b>threadName</b>
- </td>
- <td>Outputs the name of the thread that generated the logging event.</td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternThreadPriority"/>
- <b>tp</b><br />
- <b>threadPriority</b>
- </td>
- <td>Outputs the priority of the thread that generated the logging event.</td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternLoggerFqcn"/>
- <b>fqcn</b>
- </td>
- <td>Outputs the fully qualified class name of the logger.</td>
- </tr>
- <tr>
- <td align="center">
- <a name="EndOfBatch"/>
- <b>endOfBatch</b>
- </td>
- <td>Outputs the EndOfBatch status of the logging event, as "true" or "false".</td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternNDC"/>
- <b>x</b><br />
- <b>NDC</b>
- </td>
- <td>Outputs the Thread Context Stack (also known as the Nested Diagnostic Context or NDC)
- associated with the thread that generated the logging event.
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternMDC"/>
- <b>X</b>{key[,key2...]}<br />
- <b>mdc</b>{key[,key2...]}<br />
- <b>MDC</b>{key[,key2...]}
- </td>
- <td>
- <p>Outputs the Thread Context Map (also known as the Mapped Diagnostic Context or MDC)
- associated with the thread that generated the logging event. The
- <b>X</b>
- conversion character can be followed by one or more keys for the
- map placed between braces, as in
- <b>%X{clientNumber}</b>
- where
- <code>clientNumber</code>
- is the key. The value in the MDC
- corresponding to the key will be output.</p>
- <p>If a list of keys are provided, such as <b>%X{name, number}</b>, 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.</p>
- <p>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.
- </p>
- <p>See the
- <a class="javadoc" href="../log4j-api/apidocs/org/apache/logging/log4j/ThreadContext.html">ThreadContext</a>
- class for more details.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternUUID"/>
- <b>u</b>{"RANDOM" | "TIME"}<br />
- <b>uuid</b>
- </td>
- <td>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.
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternExtendedException"/>
- <b>xEx</b>|<b>xException</b>|<b>xThrowable</b><br/>
- {<br/>
- ["none" | "short" | "full" | depth]<br/>
- [,filters(package,package,...)]<br/>
- [,separator(<i>separator</i>)]<br/>
- }<br/>
- {ansi(<br/>
- Key=Value,Value,...<br/>
- Key=Value,Value,...<br/>
- ...)<br/>
- }<br/>
- {suffix(<i>pattern</i>)}<br/>
- </td>
- <td>
- <p>The same as the %throwable conversion word but also includes class packaging information.
- </p>
- <p>
- 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.
- </p>
- <p>The throwable conversion word can be followed by an option in the form
- <code>%xEx{short}</code>
- which will only output the first line of the Throwable or <code>%xEx{n}</code> where
- the first n lines of the stack trace will be printed. Specifying <code>%xEx{none}</code>
- or <code>%xEx{0}</code> will suppress printing of the exception.
- </p>
- <p>
- Use <code>filters(<i>packages</i>)</code> where <i>packages</i> is a list of package names to
- suppress matching stack frames from stack traces.
- </p>
- <p>
- Use a <code>separator</code> string to separate the lines of a stack trace. For example:
- <code>separator(|)</code>. The default value is the <code>line.separator</code> system property,
- which is operating system dependent.
- </p>
- <p>
- The <code>ansi</code> option renders stack traces with ANSI escapes code using the JAnsi library.
- (See <a href="#enable-jansi">configuration</a>.)
- Use <code>{ansi}</code> to use the default color mapping. You can specify your own mappings with
- <code>key=value</code> pairs. The keys are:
- </p>
- <ul>
- <li>Prefix</li>
- <li>Name</li>
- <li>NameMessageSeparator</li>
- <li>Message</li>
- <li>At</li>
- <li>CauseLabel</li>
- <li>Text</li>
- <li>More</li>
- <li>Suppressed</li>
- <li>StackTraceElement.ClassName</li>
- <li>StackTraceElement.ClassMethodSeparator</li>
- <li>StackTraceElement.MethodName</li>
- <li>StackTraceElement.NativeMethod</li>
- <li>StackTraceElement.FileName</li>
- <li>StackTraceElement.LineNumber</li>
- <li>StackTraceElement.Container</li>
- <li>StackTraceElement.ContainerSeparator</li>
- <li>StackTraceElement.UnknownSource</li>
- <li>ExtraClassInfo.Inexact</li>
- <li>ExtraClassInfo.Container</li>
- <li>ExtraClassInfo.ContainerSeparator</li>
- <li>ExtraClassInfo.Location</li>
- <li>ExtraClassInfo.Version</li>
- </ul>
- <p>
- The values are names from JAnsi's
- <a href="https://fusesource.github.io/jansi/documentation/api/org/fusesource/jansi/AnsiRenderer.Code.html">Code</a>
- class like <code>blue</code>, <code>bg_red</code>, and so on (Log4j ignores case.)
- </p>
- <p>
- The special key <code>StyleMapName</code> can be set to one of the following predefined maps:
- <code>Spock</code>, <code>Kirk</code>.
- </p>
- <p>
- As with %throwable, the <b>%xEx{suffix(<i>pattern</i>)</b> conversion will add the output of
- <i>pattern</i> to the output only if there is a throwable to print.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <a name="PatternPercentLiteral"/>
- <b>%</b>
- </td>
- <td>The sequence %% outputs a single percent sign.
- </td>
- </tr>
- </table>
- <p>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.
- </p>
- <p>The optional format modifier is placed between the percent sign
- and the conversion character.
- </p>
- <p>The first optional format modifier is the
- <em>left justification
- flag
- </em>
- which is just the minus (-) character. Then comes the
- optional
- <em>minimum field width</em>
- 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.
- </p>
- <p>This behavior can be changed using the
- <em>maximum field
- width
- </em>
- 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
- <em>beginning</em>
- of the data item and not from the end. For
- example, it the maximum field width is eight and the data item is
- ten characters long, then the first two characters of the data item
- are dropped. This behavior deviates from the printf function in C
- where truncation is done from the end.
- </p>
- <p>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.
- </p>
- <p>Below are various format modifier examples for the category
- conversion specifier.
- </p>
- <table>
- <tr>
- <th>Format modifier</th>
- <th>left justify</th>
- <th>minimum width</th>
- <th>maximum width</th>
- <th>comment</th>
- </tr>
- <tr>
- <td align="center">%20c</td>
- <td align="center">false</td>
- <td align="center">20</td>
- <td align="center">none</td>
- <td>Left pad with spaces if the category name is less than 20
- characters long.
- </td>
- </tr>
- <tr>
- <td align="center">%-20c</td>
- <td align="center">true</td>
- <td align="center">20</td>
- <td align="center">none</td>
- <td>Right pad with
- spaces if the category name is less than 20 characters long.
- </td>
- </tr>
- <tr>
- <td align="center">%.30c</td>
- <td align="center">NA</td>
- <td align="center">none</td>
- <td align="center">30</td>
- <td>Truncate from the beginning if the category name is longer than 30
- characters.
- </td>
- </tr>
- <tr>
- <td align="center">%20.30c</td>
- <td align="center">false</td>
- <td align="center">20</td>
- <td align="center">30</td>
- <td>Left pad with spaces if the category name is shorter than 20
- characters. However, if category name is longer than 30 characters,
- then truncate from the beginning.
- </td>
- </tr>
- <tr>
- <td align="center">%-20.30c</td>
- <td align="center">true</td>
- <td align="center">20</td>
- <td align="center">30</td>
- <td>Right pad with spaces if the category name is shorter than 20
- characters. However, if category name is longer than 30 characters,
- then truncate from the beginning.
- </td>
- </tr>
- <tr>
- <td align="center">%-20.-30c</td>
- <td align="center">true</td>
- <td align="center">20</td>
- <td align="center">30</td>
- <td>Right pad with spaces if the category name is shorter than 20
- characters. However, if category name is longer than 30 characters,
- then truncate from the end.
- </td>
- </tr>
- <caption align="top">Pattern Converters</caption>
- </table>
- <a name="enable-jansi"></a>
- <h4>ANSI Styling on Windows</h4>
- <p>ANSI escape sequences are supported natively on many platforms but are not by default on Windows. To
- enable ANSI support add the <a href="http://jansi.fusesource.org/">Jansi</a> jar to your application
- and set property <code>log4j.skipJansi</code> to <code>false</code>.
- This allows Log4j to use Jansi to add ANSI escape codes when writing to the console.
- </p>
- <p>NOTE: Prior to Log4j 2.10, Jansi was enabled by default. The fact that Jansi requires native code
- means that Jansi can only be loaded by a single class loader. For web applications this means the
- Jansi jar has to be in the web container's classpath. To avoid causing problems for web applications,
- Log4j will no longer automatically try to load Jansi without explicit configuration from Log4j 2.10 onward.</p>
- <h4>Example
<TRUNCATED>
[2/3] logging-log4j2 git commit: LOG4J2-1802: Convert layouts manual
page to asciidoc
Posted by ma...@apache.org.
LOG4J2-1802: Convert layouts manual page to asciidoc
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/f8e50945
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/f8e50945
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/f8e50945
Branch: refs/heads/master
Commit: f8e509452f6218116ba35b2b3458c9fc51c1166b
Parents: 59a9c2d
Author: Matt Sicker <bo...@gmail.com>
Authored: Sun Apr 8 21:14:47 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Sun Apr 8 21:14:47 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/manual/layouts.adoc | 2136 ++++++++++++++++++++++++
src/site/xdoc/manual/layouts.xml.vm | 2476 ----------------------------
2 files changed, 2136 insertions(+), 2476 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/f8e50945/src/site/asciidoc/manual/layouts.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/layouts.adoc b/src/site/asciidoc/manual/layouts.adoc
new file mode 100644
index 0000000..d9270ae
--- /dev/null
+++ b/src/site/asciidoc/manual/layouts.adoc
@@ -0,0 +1,2136 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+= Layouts
+Ralph Goers <rg...@apache.org>; Gary Gregory <gg...@apache.org>
+
+An Appender uses a Layout to format a LogEvent into a form that meets
+the needs of whatever will be consuming the log event. In Log4j 1.x and
+Logback Layouts were expected to transform an event into a String. In
+Log4j 2 Layouts return a byte array. This allows the result of the
+Layout to be useful in many more types of Appenders. However, this means
+you need to configure most Layouts with a
+https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[`Charset`]
+to ensure the byte array contains correct values.
+
+The root class for layouts that use a Charset is
+`org.apache.logging.log4j.core.layout.AbstractStringLayout` where the
+default is UTF-8. Each layout that extends `AbstractStringLayout` can
+provide its own default. See each layout below.
+
+A custom character encoder was added to Log4j 2.4.1 for the ISO-8859-1
+and US-ASCII charsets, to bring some of the performance improvements
+built-in to Java 8 to Log4j for use on Java 7. For applications that log
+only ISO-8859-1 characters, specifying this charset will improve
+performance significantly.
+
+[#CSVLayouts]
+== CSV Layouts
+
+As of Log4j 2.11.0, CSV support has moved from the existing module
+`logj-core` to the new module `log4j-csv`.
+
+This layout creates
+https://en.wikipedia.org/wiki/Comma-separated_values[Comma Separated
+Value (CSV)] records and requires
+https://commons.apache.org/proper/commons-csv/[Apache Commons CSV] 1.4.
+
+The CSV layout can be used in two ways: First, using
+`CsvParameterLayout` to log event parameters to create a custom
+database, usually to a logger and file appender uniquely configured for
+this purpose. Second, using `CsvLogEventLayout` to log events to create
+a database, as an alternative to using a full DBMS or using a JDBC
+driver that supports the CSV format.
+
+The `CsvParameterLayout` converts an event's parameters into a CSV
+record, ignoring the message. To log CSV records, you can use the usual
+Logger methods `info()`, `debug()`, and so on:
+
+[source,java]
+----
+logger.info("Ignored", value1, value2, value3);
+----
+
+Which will create the CSV record:
+
+....
+value1, value2, value3
+....
+
+Alternatively, you can use a `ObjectArrayMessage`, which only carries
+parameters:
+
+[source,java]
+----
+logger.info(new ObjectArrayMessage(value1, value2, value3));
+----
+
+The layouts `CsvParameterLayout` and `CsvLogEventLayout` are configured
+with the following parameters:
+
+.CsvParameterLayout and CsvLogEventLayout
+[cols="1m,1,4"]
+|===
+|Parameter Name |Type |Description
+
+|format
+|String
+|One of the predefined formats: `Default`, `Excel`,
+`MySQL`, `RFC4180`, `TDF`. See
+https://commons.apache.org/proper/commons-csv/archives/1.4/apidocs/org/apache/commons/csv/CSVFormat.Predefined.html[CSVFormat.Predefined].
+
+|delimiter
+|Character
+|Sets the delimiter of the format to the specified character.
+
+|escape
+|Character
+|Sets the escape character of the format to the specified character.
+
+|quote
+|Character
+|Sets the quoteChar of the format to the specified
+character.
+
+|quoteMode
+|String
+|Sets the output quote policy of the format to the
+specified value. One of: `ALL`, `MINIMAL`, `NON_NUMERIC`, `NONE`.
+
+|nullString
+|String
+|Writes null as the given nullString when writing records.
+
+|recordSeparator
+|String
+|Sets the record separator of the format to the specified String.
+
+|charset
+|Charset
+|The output Charset.
+
+|header
+|Sets the header to include when the stream is opened.
+|Desc.
+
+|footer
+|Sets the footer to include when the stream is closed.
+|Desc.
+|===
+
+Logging as a CSV events looks like this:
+
+[source,java]
+----
+logger.debug("one={}, two={}, three={}", 1, 2, 3);
+----
+
+Produces a CSV record with the following fields:
+
+1. Time Nanos
+2. Time Millis
+3. Level
+4. Thread ID
+5. Thread Name
+6. Thread Priority
+7. Formatted Message
+8. Logger FQCN
+9. Logger Name
+10. Marker
+11. Thrown Proxy
+12. Source
+13. Context Map
+14. Context Stack
+
+....
+0,1441617184044,DEBUG,main,"one=1, two=2, three=3",org.apache.logging.log4j.spi.AbstractLogger,,,,org.apache.logging.log4j.core.layout.CsvLogEventLayoutTest.testLayout(CsvLogEventLayoutTest.java:98),{},[]
+....
+
+Additional link:../runtime-dependencies.html[runtime dependencies] are
+required for using CSV layouts.
+
+[#GELFLayout]
+== GELF Layout
+
+Lays out events in the Graylog Extended Log Format (GELF) 1.1.
+
+This layout compresses JSON to GZIP or ZLIB (the `compressionType`) if
+log event data is larger than 1024 bytes (the `compressionThreshold`).
+This layout does not implement chunking.
+
+Configure as follows to send to a Graylog 2.x server with UDP:
+
+[source,xml]
+----
+<Appenders>
+ <Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201">
+ <GelfLayout host="someserver" compressionType="ZLIB" compressionThreshold="1024"/>
+ </Socket>
+</Appenders>
+----
+
+Configure as follows to send to a Graylog 2.x server with TCP:
+
+[source,xml]
+----
+<Appenders>
+ <Socket name="Graylog" protocol="tcp" host="graylog.domain.com" port="12201">
+ <GelfLayout host="someserver" compressionType="OFF" includeNullDelimiter="true"/>
+ </Socket>
+</Appenders>
+----
+
+.GelfLayout Parameters
+[cols="1m,1,4"]
+|===
+|Parameter Name |Type |Description
+
+|host
+|String
+|The value of the `host` property (optional, defaults to local host name).
+
+|compressionType
+|`GZIP`, `ZLIB` or `OFF`
+|Compression to use (optional, defaults to `GZIP`)
+
+|compressionThreshold
+|int
+|Compress if data is larger than this number of bytes (optional, defaults to 1024)
+
+|includeStacktrace
+|boolean
+|Whether to include full stacktrace of logged Throwables (optional, default to true).
+If set to false, only the class name and message of the
+https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html[Throwable]
+will be included.
+
+|includeThreadContext
+|boolean
+|Whether to include thread context as additional fields (optional, default to true).
+
+|includeNullDelimiter
+|boolean
+|Whether to include NULL byte as delimiter after each event (optional, default to false).
+Useful for Graylog GELF TCP input. Cannot be used with compression.
+|===
+
+To include any custom field in the output, use following syntax:
+
+[source,xml]
+----
+<GelfLayout>
+ <KeyValuePair key="additionalField1" value="constant value"/>
+ <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
+</GelfLayout>
+----
+
+Custom fields are included in the order they are declared. The values
+support link:lookups.html[lookups].
+
+See also:
+
+* The http://docs.graylog.org/en/latest/pages/gelf.html#gelf[GELF
+specification]
+
+[#HTMLLayout]
+== HTML Layout
+
+The HtmlLayout generates an HTML page and adds each LogEvent to a row in
+a table.
+
+.HtmlLayout Parameters
+[cols="1m,1,4"]
+|===
+|Parameter Name |Type |Description
+
+|charset
+|String
+|The character set to use when converting the HTML
+String to a byte array. The value must be a valid
+http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
+If not specified, this layout uses UTF-8.
+
+|contentType
+|String
+|The value to assign to the Content-Type header.
+The default is "text/html".
+
+|locationInfo
+|boolean
+a|[[HtmlLocationInfo]]
+
+If true, the filename and line number will be included in the HTML
+output. The default value is false.
+
+Generating link:#LocationInformation[location information] is an
+expensive operation and may impact performance. Use with caution.
+
+|title
+|String
+|A String that will appear as the HTML title.
+
+|fontName
+|String
+|The `font-family` to use. The default is "arial,sans-serif".
+
+|fontSize
+|String
+|The `font-size` to use. The default is "small".
+|===
+
+[#JSONLayout]
+== JSON Layout
+
+Appends a series of JSON events as strings serialized as bytes.
+
+=== Complete well-formed JSON vs. fragment JSON
+
+If you configure `complete="true"`, the appender outputs a well-formed
+JSON document. By default, with `complete="false"`, you should include
+the output as an _external file_ in a separate file to form a
+well-formed JSON document.
+
+If `complete="false"`, the appender does not write the JSON open array
+character "[" at the start of the document, "]" and the end, nor comma
+"," between records.
+
+Log event follows this pattern:
+
+[source,json]
+----
+{
+ "instant" : {
+ "epochSecond" : 1493121664,
+ "nanoOfSecond" : 118000000
+ },
+ "thread" : "main",
+ "level" : "INFO",
+ "loggerName" : "HelloWorld",
+ "marker" : {
+ "name" : "child",
+ "parents" : [ {
+ "name" : "parent",
+ "parents" : [ {
+ "name" : "grandparent"
+ } ]
+ } ]
+ },
+ "message" : "Hello, world!",
+ "thrown" : {
+ "commonElementCount" : 0,
+ "message" : "error message",
+ "name" : "java.lang.RuntimeException",
+ "extendedStackTrace" : [ {
+ "class" : "logtest.Main",
+ "method" : "main",
+ "file" : "Main.java",
+ "line" : 29,
+ "exact" : true,
+ "location" : "classes/",
+ "version" : "?"
+ } ]
+ },
+ "contextStack" : [ "one", "two" ],
+ "endOfBatch" : false,
+ "loggerFqcn" : "org.apache.logging.log4j.spi.AbstractLogger",
+ "contextMap" : {
+ "bar" : "BAR",
+ "foo" : "FOO"
+ },
+ "threadId" : 1,
+ "threadPriority" : 5,
+ "source" : {
+ "class" : "logtest.Main",
+ "method" : "main",
+ "file" : "Main.java",
+ "line" : 29
+ }
+}
+----
+
+If `complete="false"`, the appender does not write the JSON open array
+character "[" at the start of the document, "]" and the end, nor comma
+"," between records.
+
+=== Pretty vs. compact JSON
+
+By default, the JSON layout is not compact (a.k.a. not "pretty") with
+`compact="false"`, which means the appender uses end-of-line characters
+and indents lines to format the text. If `compact="true"`, then no
+end-of-line or indentation is used. Message content may contain, of
+course, escaped end-of-lines.
+
+.JsonLayout Parameters
+[cols="1m,1,4"]
+|===
+|Parameter Name |Type |Description
+
+|charset
+|String
+|The character set to use when converting to a byte
+array. The value must be a valid
+http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
+If not specified, UTF-8 will be used.
+
+|compact
+|boolean
+|If true, the appender does not use end-of-lines and
+indentation. Defaults to false.
+
+|eventEol
+|boolean
+|If true, the appender appends an end-of-line after
+each record. Defaults to false. Use with eventEol=true and compact=true
+to get one record per line.
+
+|complete
+|boolean
+|If true, the appender includes the JSON header and
+footer, and comma between records. Defaults to false.
+
+|properties
+|boolean
+|If true, the appender includes the thread context
+map in the generated JSON. Defaults to false.
+
+|propertiesAsList
+|boolean
+|If true, the thread context map is included
+as a list of map entry objects, where each entry has a "key" attribute
+(whose value is the key) and a "value" attribute (whose value is the
+value). Defaults to false, in which case the thread context map is
+included as a simple map of key-value pairs.
+
+|locationInfo
+|boolean
+a|
+If true, the appender includes the location information in the generated
+JSON. Defaults to false.
+
+Generating link:#LocationInformation[location information] is an
+expensive operation and may impact performance. Use with caution.
+
+|includeStacktrace
+|boolean
+|If true, include full stacktrace of any logged
+https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html[Throwable]
+(optional, default to true).
+
+|stacktraceAsString
+|boolean
+|Whether to format the stacktrace as a
+string, and not a nested object (optional, defaults to false).
+
+|includeNullDelimiter
+|boolean
+|Whether to include NULL byte as
+delimiter after each event (optional, default to false).
+
+|objectMessageAsJsonObject
+|boolean
+|If true, ObjectMessage is
+serialized as JSON object to the "message" field of the output log.
+Defaults to false.
+|===
+
+To include any custom field in the output, use following syntax:
+
+[source,xml]
+----
+<JsonLayout>
+ <KeyValuePair key="additionalField1" value="constant value"/>
+ <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
+</JsonLayout>
+----
+
+Custom fields are always last, in the order they are declared. The
+values support link:lookups.html[lookups].
+
+Additional link:../runtime-dependencies.html[runtime dependencies] are
+required for using JsonLayout.
+
+[#PatternLayout]
+== Pattern Layout
+
+A flexible layout configurable with pattern string. The goal of this
+class is to format a LogEvent and return the results. The format of the
+result depends on the _conversion pattern_.
+
+The conversion pattern is closely related to the conversion pattern of
+the printf function in C. A conversion pattern is composed of literal
+text and format control expressions called _conversion specifiers_.
+
+_Note that any literal text, including *Special Characters*, may be
+included in the conversion pattern._ Special Characters include *\t*,
+*\n*, *\r*, *\f*. Use *\\* to insert a single backslash into the output.
+
+Each conversion specifier starts with a percent sign (%) and is followed
+by optional _format modifiers_ and a _conversion character_. The
+conversion character specifies the type of data, e.g. category,
+priority, date, thread name. The format modifiers control such things as
+field width, padding, left and right justification. The following is a
+simple example.
+
+Let the conversion pattern be *"%-5p [%t]: %m%n"* and assume that the
+Log4j environment was set to use a PatternLayout. Then the statements
+
+....
+Logger logger = LogManager.getLogger("MyLogger");
+logger.debug("Message 1");
+logger.warn("Message 2");
+....
+
+would yield the output
+
+....
+DEBUG [main]: Message 1
+WARN [main]: Message 2
+....
+
+Note that there is no explicit separator between text and conversion
+specifiers. The pattern parser knows when it has reached the end of a
+conversion specifier when it reads a conversion character. In the
+example above the conversion specifier *%-5p* means the priority of the
+logging event should be left justified to a width of five characters.
+
+If the pattern string does not contain a specifier to handle a Throwable
+being logged, parsing of the pattern will act as if the "%xEx" specifier
+had be added to the end of the string. To suppress formatting of the
+Throwable completely simply add "%ex{0}" as a specifier in the pattern
+string.
+
+.PatternLayout Parameters
+[cols="1m,1,4"]
+|===
+|Parameter Name |Type |Description
+
+|charset
+|String
+|The character set to use when converting the syslog
+String to a byte array. The String must be a valid
+http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
+If not specified, this layout uses the platform default character set.
+
+|pattern
+|String
+|A composite pattern string of one or more conversion
+patterns from the table below. Cannot be specified with a
+PatternSelector.
+
+|patternSelector
+|PatternSelector
+|A component that analyzes information
+in the LogEvent and determines which pattern should be used to format
+the event. The pattern and patternSelector parameters are mutually
+exclusive.
+
+|replace
+|RegexReplacement
+|Allows portions of the resulting String to
+be replaced. If configured, the replace element must specify the regular
+expression to match and the substitution. This performs a function
+similar to the RegexReplacement converter but applies to the whole
+message while the converter only applies to the String its pattern
+generates.
+
+|alwaysWriteExceptions
+|boolean
+|If `true` (it is by default) exceptions
+are always written even if the pattern contains no exception
+conversions. This means that if you do not include a way to output
+exceptions in your pattern, the default exception formatter will be
+added to the end of the pattern. Setting this to `false` disables this
+behavior and allows you to exclude exceptions from your pattern output.
+
+|header
+|String
+|The optional header string to include at the top of
+each log file.
+
+|footer
+|String
+|The optional footer string to include at the bottom of
+each log file.
+
+|disableAnsi
+|boolean
+|If `true` (default is false), do not output ANSI
+escape codes.
+
+|noConsoleNoAnsi
+|boolean
+|If `true` (default is false) and
+`System.console()` is null, do not output ANSI escape codes.
+|===
+
+.RegexReplacement Parameters
+|===
+|Parameter Name |Type |Description
+
+|regex
+|String
+|A Java-compliant regular expression to match in the resulting string. See
+https://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[Pattern].
+
+|replacement
+|String
+|The string to replace any matched sub-strings with.
+|===
+
+[#Patterns]
+=== Patterns
+
+The conversions that are provided with Log4j are:
+
+[cols="1,3a"]
+|===
+|Conversion Pattern |Description
+
+|*c*{precision} +
+*logger*{precision}
+|Outputs the name of the logger that published the logging event. The
+logger conversion specifier can be optionally followed by _precision
+specifier_, which consists of a decimal integer, or a pattern starting
+with a decimal integer.
+
+When the precision specifier is an integer value, it reduces the size of
+the logger name. If the number is positive, the layout prints the
+corresponding number of rightmost logger name components. If negative,
+the layout removes the corresponding number of leftmost logger name
+components.
+
+If the precision contains any non-integer characters, then the layout
+abbreviates the name based on the pattern. If the precision integer is
+less than one, the layout still prints the right-most token in full. By
+default, the layout prints the logger name in full.
+
+!===
+!Conversion Pattern !Logger Name !Result
+
+!%c{1}
+!org.apache.commons.Foo
+!Foo
+
+!%c{2}
+!org.apache.commons.Foo
+!commons.Foo
+
+!%c{10}
+!org.apache.commons.Foo
+!org.apache.commons.Foo
+
+!%c{-1}
+!org.apache.commons.Foo
+!apache.commons.Foo
+
+!%c{-2}
+!org.apache.commons.Foo
+!commons.Foo
+
+!%c{-10}
+!org.apache.commons.Foo
+!org.apache.commons.Foo
+
+!%c{1.}
+!org.apache.commons.Foo
+!o.a.c.Foo
+
+!%c{1.1.~.~}
+!org.apache.commons.test.Foo
+!o.a.~.~.Foo
+
+!%c{.}
+!org.apache.commons.test.Foo
+!....Foo
+!===
+
+|[[PatternClass]] *C*{precision} +
+*class*{precision}
+|Outputs the fully qualified class name of the caller issuing the logging
+request. This conversion specifier can be optionally followed by
+_precision specifier_, that follows the same rules as the logger name
+converter.
+
+Generating the class name of the caller
+(link:#LocationInformation[location information]) is an expensive
+operation and may impact performance. Use with caution.
+
+|*d*{pattern} +
+*date*{pattern}
+|Outputs the date of the logging event. The date conversion specifier may
+be followed by a set of braces containing a date and time pattern string per
+https://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html[`SimpleDateFormat`].
+
+The predefined formats are `DEFAULT`, `ABSOLUTE`, `COMPACT`, `DATE`,
+`ISO8601`, and `ISO8601_BASIC`.
+
+You can also use a set of braces containing a time zone id per
+https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)[java.util.TimeZone.getTimeZone].
+If no date format specifier is given then the DEFAULT format is used.
+
+[cols=",",options="header",]
+!===
+!Pattern !Example
+
+!%d{DEFAULT}
+!2012-11-02 14:34:02,123
+
+!%d{DEFAULT_MICROS}
+!2012-11-02 14:34:02,123456
+
+!%d{DEFAULT_NANOS}
+!2012-11-02 14:34:02,123456789
+
+!%d{ISO8601}
+!2012-11-02T14:34:02,781
+
+!%d{ISO8601_BASIC}
+!20121102T143402,781
+
+!%d{ABSOLUTE}
+!14:34:02,781
+
+!%d{ABSOLUTE_MICROS}
+!14:34:02,123456
+
+!%d{ABSOLUTE_NANOS}
+!14:34:02,123456789
+
+!%d{DATE}
+!02 Nov 2012 14:34:02,781
+
+!%d{COMPACT}
+!20121102143402781
+
+!%d{HH:mm:ss,SSS}
+!14:34:02,123
+
+!%d{HH:mm:ss,nnnn} to %d{HH:mm:ss,nnnnnnnnn}
+!14:34:02,1234 to 14:34:02,123456789
+
+!%d{dd MMM yyyy HH:mm:ss,SSS}
+!02 Nov 2012 14:34:02,123
+
+!%d{dd MMM yyyy HH:mm:ss,nnnn} to %d{dd MMM yyyy HH:mm:ss,nnnnnnnnn}
+!02 Nov 2012 14:34:02,1234 to 02 Nov 2012 14:34:02,123456789
+
+!%d{HH:mm:ss}{GMT+0}
+!18:34:02
+
+!%d{UNIX}
+!1351866842
+
+!%d{UNIX_MILLIS}
+!1351866842781
+!===
+
+%d{UNIX} outputs the UNIX time in seconds. %d{UNIX_MILLIS} outputs the
+UNIX time in milliseconds. The UNIX time is the difference, in seconds
+for UNIX and in milliseconds for UNIX_MILLIS, between the current time
+and midnight, January 1, 1970 UTC. While the time unit is milliseconds,
+the granularity depends on the operating system
+(http://msdn.microsoft.com/en-us/windows/hardware/gg463266.aspx[Windows]).
+This is an efficient way to output the event time because only a
+conversion from long to String takes place, there is no Date formatting
+involved.
+
+Log4j 2.11 adds limited support for timestamps more precise than
+milliseconds when running on Java 9. Note that not all
+https://docs.oracle.com/javase/9/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter]
+formats are supported. Only timestamps in the formats mentioned in the
+table above may use the "nano-of-second" pattern letter `n` instead of
+the "fraction-of-second" pattern letter `S`.
+
+Users may revert back to a millisecond-precision clock when running on
+Java 9 by setting system property `log4j2.Clock` to `SystemMillisClock`.
+
+|*enc*{_pattern_}{[HTML\|XML\|JSON\|CRLF]} +
+*encode*{_pattern_}{[HTML\|XML\|JSON\|CRLF]}
+|Encodes and escapes special characters suitable for output in specific
+markup languages. By default, this encodes for HTML if only one option
+is specified. The second option is used to specify which encoding format
+should be used. This converter is particularly useful for encoding user
+provided data so that the output data is not written improperly or
+insecurely.
+
+A typical usage would encode the message `%enc{%m}` but user input could
+come from other locations as well, such as the MDC `%enc{%mdc{key}}`
+
+Using the HTML encoding format, the following characters are replaced:
+
+!===
+!Character !Replacement
+
+!'\r', '\n'
+!Converted into escaped strings "\\r" and "\\n" respectively
+
+!&, <, >, ", ', /
+!Replaced with the corresponding HTML entity
+!===
+
+Using the XML encoding format, this follows the escaping rules specified
+by https://www.w3.org/TR/xml/[the XML specification]:
+
+!===
+!Character !Replacement
+
+!&, <, >, ", '
+!Replaced with the corresponding XML entity
+!===
+
+Using the JSON encoding format, this follows the escaping rules
+specified by https://www.ietf.org/rfc/rfc4627.txt[RFC 4627 section 2.5]:
+
+!===
+!Character !Replacement
+
+!U+0000 - U+001F
+!\u0000 - \u001F
+
+!Any other control characters
+!Encoded into its `\uABCD` equivalent escaped code point
+
+!"
+!\"
+
+!\
+!\\
+!===
+
+For example, the pattern `{"message": "%enc{%m}{JSON}"}` could be used
+to output a valid JSON document containing the log message as a string
+value.
+
+Using the CRLF encoding format, the following characters are replaced:
+
+!===
+!Character !Replacement
+
+!'\r', '\n'
+!Converted into escaped strings "\\r" and "\\n" respectively
+!===
+
+|*equals*{pattern}{test}{substitution} +
+*equalsIgnoreCase*{pattern}{test}{substitution}
+|Replaces occurrences of 'test', a string, with its replacement
+'substitution' in the string resulting from evaluation of the pattern.
+For example, "%equals{[%marker]}{[]}\{}" will replace '[]' strings
+produces by events without markers with an empty string.
+
+The pattern can be arbitrarily complex and in particular can contain
+multiple conversion keywords.
+
+|**ex**\|**exception**\|*throwable* +
+{ +
+ [ "none" +
+ \| "full" +
+ \| depth +
+ \| "short" +
+ \| "short.className" +
+ \| "short.fileName" +
+ \| "short.lineNumber" +
+ \| "short.methodName" +
+ \| "short.message" +
+ \| "short.localizedMessage"] +
+} +
+ {filters(package,package,...)} +
+ {suffix(_pattern_)} +
+ {separator(_separator_)}
+|Outputs the Throwable trace bound to the logging event, by default this
+will output the full trace as one would normally find with a call to
+`Throwable.printStackTrace()`.
+
+You can follow the throwable conversion word with an option in the form
+`%throwable{option}`.
+
+`%throwable{short}` outputs the first line of the Throwable.
+
+`%throwable{short.className}` outputs the name of the class where the
+exception occurred.
+
+`%throwable{short.methodName}` outputs the method name where the
+exception occurred.
+
+`%throwable{short.fileName}` outputs the name of the class where the
+exception occurred.
+
+`%throwable{short.lineNumber}` outputs the line number where the
+exception occurred.
+
+`%throwable{short.message}` outputs the message.
+
+`%throwable{short.localizedMessage}` outputs the localized message.
+
+`%throwable{n}` outputs the first n lines of the stack trace.
+
+Specifying `%throwable{none}` or `%throwable{0}` suppresses output of
+the exception.
+
+Use `{filters(packages)}` where _packages_ is a list of package names to
+suppress matching stack frames from stack traces.
+
+Use `{suffix(pattern)}` to add the output of _pattern_ at the end of
+each stack frames.
+
+Use a `{separator(...)}` as the end-of-line string. For example:
+`separator(\|)`. The default value is the `line.separator` system
+property, which is operating system dependent.
+
+|[[PatternFile]] *F* +
+*file*
+|Outputs the file name where the logging request was issued.
+
+Generating the file information (link:#LocationInformation[location
+information]) is an expensive operation and may impact performance. Use
+with caution.
+
+|*highlight*{pattern}{style}
+|Adds ANSI colors to the result of the enclosed pattern based on the
+current event's logging level. (See Jansi link:#enable-jansi[configuration].)
+
+The default colors for each level are:
+
+!===
+!Level !ANSI color
+
+!FATAL
+!Bright red
+
+!ERROR
+!Bright red
+
+!WARN
+!Yellow
+
+!INFO
+!Green
+
+!DEBUG
+!Cyan
+
+!TRACE
+!Black (looks dark grey)
+!===
+
+The color names are ANSI names defined in the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/pattern/AnsiEscape.html[`AnsiEscape`]
+class.
+
+The color and attribute names and are standard, but the exact shade,
+hue, or value.
+
+.Color table
+!===
+!Intensity Code !0 !1 !2 !3 !4 !5 !6 !7
+
+!Normal !Black !Red !Green !Yellow !Blue !Magenta !Cyan !White
+
+!Bright !Black !Red !Green !Yellow !Blue !Magenta !Cyan !White
+!===
+
+You can use the default colors with:
+
+....
+%highlight{%d [%t] %-5level: %msg%n%throwable}
+....
+
+You can override the default colors in the optional {style} option. For
+example:
+
+....
+%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}
+....
+
+You can highlight only the a portion of the log event:
+
+....
+%d [%t] %highlight{%-5level: %msg%n%throwable}
+....
+
+You can style one part of the message and highlight the rest the log
+event:
+
+....
+%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}
+....
+
+You can also use the STYLE key to use a predefined group of colors:
+
+....
+%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}
+....
+
+The STYLE value can be one of:
+
+* Default: see above
+* Logback:
+!===
+!Level !ANSI color
+
+!FATAL !Blinking bright red
+
+!ERROR !Bright red
+
+!WARN !Red
+
+!INFO !Blue
+
+!DEBUG !Normal
+
+!TRACE !Normal
+!===
+
+|[[PatternMap]] *K*{key} +
+*map*{key} +
+*MAP*{key}
+|Outputs the entries in a
+link:../log4j-api/apidocs/org/apache/logging/log4j/message/MapMessage.html[MapMessage],
+if one is present in the event. The *K* conversion character can be
+followed by the key for the map placed between braces, as in
+*%K{clientNumber}* where `clientNumber` is the key. The value in the
+Map corresponding to the key will be output. If no additional sub-option
+is specified, then the entire contents of the Map key value pair set is
+output using a format {{key1,val1},{key2,val2}}
+
+|[[PatternLocation]] *l* +
+*location*
+|Outputs location information of the caller which generated the logging event.
+
+The location information depends on the JVM implementation but usually
+consists of the fully qualified name of the calling method followed by
+the callers source the file name and line number between parentheses.
+
+Generating link:#LocationInformation[location information] is an
+expensive operation and may impact performance. Use with caution.
+
+|[[PatternLine]] *L* +
+*line*
+|Outputs the line number from where the logging request was issued.
+
+Generating line number information (link:#LocationInformation[location
+information]) is an expensive operation and may impact performance. Use
+with caution.
+
+|[[PatternMessage]] *m*{nolookups}{ansi} +
+*msg*{nolookups}{ansi} +
+*message*{nolookups}{ansi}
+|Outputs the application supplied message associated with the logging
+event.
+
+Add `{ansi}` to render messages with ANSI escape codes (requires JAnsi,
+see link:#enable-jansi[configuration].)
+
+The default syntax for embedded ANSI codes is:
+
+....
+@\|code(,code)* text\|@
+....
+
+For example, to render the message `"Hello"` in green, use:
+
+....
+@\|green Hello\|@
+....
+
+To render the message `"Hello"` in bold and red, use:
+
+....
+@\|bold,red Warning!\|@
+....
+
+You can also define custom style names in the configuration with the
+syntax:
+
+....
+%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n
+....
+
+For example:
+
+....
+%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n
+....
+
+The call site can look like this:
+
+....
+logger.info("@\|KeyStyle {}\|@ = @\|ValueStyle {}\|@", entry.getKey(), entry.getValue());
+....
+
+Use `{nolookups}` to log messages like `"${date:YYYY-MM-dd}"` without
+using any lookups. Normally calling
+`logger.info("Try ${date:YYYY-MM-dd}")` would replace the date template
+`${date:YYYY-MM-dd}` with an actual date. Using `nolookups` disables
+this feature and logs the message string untouched.
+
+|[[PatternMethod]] *M* +
+*method*
+|Outputs the method name where the logging request was issued.
+
+Generating the method name of the caller
+(link:#LocationInformation[location information]) is an expensive
+operation and may impact performance. Use with caution.
+
+|[[PatternMarker]] *marker*
+|The full name of the marker, including parents, if one is present.
+
+|[[PatternMarkerSimpleName]] *markerSimpleName*
+|The simple name of the marker (not including parents), if one is present.
+
+|[[PatternMaxLength]] *maxLen* +
+*maxLength*
+|Outputs the result of evaluating the pattern and truncating the result.
+If the length is greater than 20, then the output will contain a
+trailing ellipsis. If the provided length is invalid, a default value of
+100 is used.
+
+Example syntax: `%maxLen{%p: %c{1} - %m%notEmpty{ =>%ex{short}}}{160}`
+will be limited to 160 characters with a trailing ellipsis. Another
+example: `%maxLen{%m}{20}` will be limited to 20 characters and no
+trailing ellipsis.
+
+|[[PatternNewLine]] *n*
+|Outputs the platform dependent line separator character or characters.
+
+This conversion character offers practically the same performance as
+using non-portable line separator strings such as "\n", or "\r\n". Thus,
+it is the preferred way of specifying a line separator.
+
+|[[NanoTime]] *N* +
+*nano*
+|Outputs the result of `System.nanoTime()` at the time the log
+event was created.
+
+|[[Process_ID]] *pid*{[defaultValue]} +
+*processId*{[defaultValue]}
+|Outputs the process ID if supported by the
+underlying platform. An optional default value may be specified to be
+shown if the platform does not support process IDs.
+
+|[[VariablesNotEmpty]] *variablesNotEmpty*{pattern} +
+*varsNotEmpty*{pattern} +
+*notEmpty*{pattern}
+|Outputs the result of evaluating the pattern if and only if all
+variables in the pattern are not empty.
+
+For example:
+
+....
+%notEmpty{[%marker]}
+....
+
+|[[PatternLevel]] **p**\|*level*{__level__=_label_, __level__=_label_,
+...} **p**\|*level*{length=_n_}
+**p**\|*level*{lowerCase=__true__\|_false_}
+|Outputs the level of the logging event. You provide a level name map in
+the form "level=value, level=value" where level is the name of the Level
+and value is the value that should be displayed instead of the name of
+the Level.
+
+For example:
+
+....
+%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}
+....
+
+Alternatively, for the compact-minded:
+
+....
+%level{WARN=W, DEBUG=D, ERROR=E, TRACE=T, INFO=I}
+....
+
+More succinctly, for the same result as above, you can define the length
+of the level label:
+
+....
+%level{length=1}
+....
+
+If the length is greater than a level name length, the layout uses the
+normal level name.
+
+You can combine the two kinds of options:
+
+....
+%level{ERROR=Error, length=2}
+....
+
+This give you the `Error` level name and all other level names of length
+2.
+
+Finally, you can output lower-case level names (the default is
+upper-case):
+
+....
+%level{lowerCase=true}
+....
+
+|[[PatternRelative]] *r* +
+*relative*
+|Outputs the number of milliseconds elapsed since the JVM was
+started until the creation of the logging event.
+
+|[[PatternReplace]] *replace*{pattern}{regex}{substitution}
+|Replaces occurrences of 'regex', a regular expression, with its
+replacement 'substitution' in the string resulting from evaluation of
+the pattern. For example, "%replace{%msg}{\s}\{}" will remove all
+spaces contained in the event message.
+
+The pattern can be arbitrarily complex and in particular can contain
+multiple conversion keywords. For instance, "%replace{%logger
+%msg}{\.}{/}" will replace all dots in the logger or the message of
+the event with a forward slash.
+
+|[[PatternException]] **rEx**\|**rException**\|*rThrowable* +
+ { +
+ ["none" \| "short" \| "full" \| depth] +
+ [,filters(package,package,...)] +
+ [,separator(_separator_)] +
+ } +
+ {ansi( +
+ Key=Value,Value,... +
+ Key=Value,Value,... +
+ ...) +
+ } +
+ {suffix(_pattern_)} +
+|The same as the %throwable conversion word but the stack trace is
+printed starting with the first exception that was thrown followed by
+each subsequent wrapping exception.
+
+The throwable conversion word can be followed by an option in the form
+`%rEx{short}` which will only output the first line of the Throwable or
+`%rEx{n}` where the first n lines of the stack trace will be printed.
+
+Specifying `%rEx{none}` or `%rEx{0}` will suppress printing of the
+exception.
+
+Use `filters(packages)` where _packages_ is a list of package names to
+suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace. For
+example: `separator(\|)`. The default value is the `line.separator`
+system property, which is operating system dependent.
+
+Use `rEx{suffix(pattern)` to add the output of _pattern_ to the output
+only when there is a throwable to print.
+
+|[[PatternSequenceNumber]] *sn* +
+*sequenceNumber*
+|Includes a sequence number that will be incremented in
+every event. The counter is a static variable so will only be unique
+within applications that share the same converter Class object.
+
+|[[PatternStyle]] *style*{pattern}{ANSI style}
+|Uses ANSI escape sequences to style the result of the enclosed pattern.
+The style can consist of a comma separated list of style names from the
+following table. (See Jansi link:#enable-jansi[configuration].)
+
+!===
+!Style Name !Description
+
+!Normal
+!Normal display
+
+!Bright
+!Bold
+
+!Dim
+!Dimmed or faint characters
+
+!Underline
+!Underlined characters
+
+!Blink
+!Blinking characters
+
+!Reverse
+!Reverse video
+
+!Hidden
+!
+
+!Black or FG_Black
+!Set foreground color to black
+
+!Red or FG_Red
+!Set foreground color to red
+
+!Green or FG_Green
+!Set foreground color to green
+
+!Yellow or FG_Yellow
+!Set foreground color to yellow
+
+!Blue or FG_Blue
+!Set foreground color to blue
+
+!Magenta or FG_Magenta
+!Set foreground color to magenta
+
+!Cyan or FG_Cyan
+!Set foreground color to cyan
+
+!White or FG_White
+!Set foreground color to white
+
+!Default or FG_Default
+!Set foreground color to default (white)
+
+!BG_Black
+!Set background color to black
+
+!BG_Red
+!Set background color to red
+
+!BG_Green
+!Set background color to green
+
+!BG_Yellow
+!Set background color to yellow
+
+!BG_Blue
+!Set background color to blue
+
+!BG_Magenta
+!Set background color to magenta
+
+!BG_Cyan
+!Set background color to cyan
+
+!BG_White
+!Set background color to white
+!===
+
+For example:
+
+....
+%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}
+....
+
+You can also combine styles:
+
+....
+%d %highlight{%p} %style{%logger}{bright,cyan} %C{1.} %msg%n
+....
+
+You can also use `%` with a color like `%black`, `%blue`, `%cyan`, and
+so on. For example:
+
+....
+%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}
+....
+
+|[[PatternThreadId]] *T* +
+*tid* +
+*threadId*
+|Outputs the ID of the thread that generated the logging event.
+
+|[[PatternThreadName]] *t* +
+*tn* +
+*thread* +
+*threadName*
+|Outputs the name of the thread that generated the logging event.
+
+|[[PatternThreadPriority]] *tp* +
+*threadPriority*
+|Outputs the priority of the thread that generated the logging event.
+
+|[[PatternLoggerFqcn]] *fqcn*
+|Outputs the fully qualified class name of the logger.
+
+|[[EndOfBatch]] *endOfBatch*
+|Outputs the EndOfBatch status of the logging event, as "true" or "false".
+
+|[[PatternNDC]] *x* +
+*NDC*
+|Outputs the Thread Context Stack (also known as the Nested
+Diagnostic Context or NDC) associated with the thread that generated the
+logging event.
+
+|[[PatternMDC]] *X*{key[,key2...]} +
+*mdc*{key[,key2...]} +
+*MDC*{key[,key2...]}
+|Outputs the Thread Context Map (also known as the Mapped Diagnostic
+Context or MDC) associated with the thread that generated the logging
+event. The *X* conversion character can be followed by one or more keys
+for the map placed between braces, as in *%X{clientNumber}* where
+`clientNumber` is the key. The value in the MDC corresponding to the key
+will be output.
+
+If a list of keys are provided, such as *%X{name, number}*, then each
+key that is present in the ThreadContext will be output using the format
+{name=val1, number=val2}. The key/value pairs will be printed in the
+order they appear in the list.
+
+If no sub-options are specified then the entire contents of the MDC key
+value pair set is output using a format {key1=val1, key2=val2}. The
+key/value pairs will be printed in sorted order.
+
+See the
+link:../log4j-api/apidocs/org/apache/logging/log4j/ThreadContext.html[ThreadContext]
+class for more details.
+
+|[[PatternUUID]] *u*{"RANDOM" \| "TIME"} +
+*uuid*
+|Includes either a random or a time-based UUID. The time-based
+UUID is a Type 1 UUID that can generate up to 10,000 unique ids per
+millisecond, will use the MAC address of each host, and to try to insure
+uniqueness across multiple JVMs and/or ClassLoaders on the same host a
+random number between 0 and 16,384 will be associated with each instance
+of the UUID generator Class and included in each time-based UUID
+generated. Because time-based UUIDs contain the MAC address and
+timestamp they should be used with care as they can cause a security
+vulnerability.
+
+|[[PatternExtendedException]] **xEx**\|**xException**\|*xThrowable* +
+ { +
+ ["none" \| "short" \| "full" \| depth] +
+ [,filters(package,package,...)] +
+ [,separator(_separator_)] +
+ } +
+ {ansi( +
+ Key=Value,Value,... +
+ Key=Value,Value,... +
+ ...) +
+ } +
+ {suffix(_pattern_)} +
+|The same as the %throwable conversion word but also includes class
+packaging information.
+
+At the end of each stack element of the exception, a string containing
+the name of the jar file that contains the class or the directory the
+class is located in and the "Implementation-Version" as found in that
+jar's manifest will be added. If the information is uncertain, then the
+class packaging data will be preceded by a tilde, i.e. the '~'
+character.
+
+The throwable conversion word can be followed by an option in the form
+`%xEx{short}` which will only output the first line of the Throwable or
+`%xEx{n}` where the first n lines of the stack trace will be printed.
+Specifying `%xEx{none}` or `%xEx{0}` will suppress printing of the
+exception.
+
+Use `filters(packages)` where _packages_ is a list of package names to
+suppress matching stack frames from stack traces.
+
+Use a `separator` string to separate the lines of a stack trace. For
+example: `separator(\|)`. The default value is the `line.separator`
+system property, which is operating system dependent.
+
+The `ansi` option renders stack traces with ANSI escapes code using the
+JAnsi library. (See link:#enable-jansi[configuration].) Use `{ansi}` to
+use the default color mapping. You can specify your own mappings with
+`key=value` pairs. The keys are:
+
+* Prefix
+* Name
+* NameMessageSeparator
+* Message
+* At
+* CauseLabel
+* Text
+* More
+* Suppressed
+* StackTraceElement.ClassName
+* StackTraceElement.ClassMethodSeparator
+* StackTraceElement.MethodName
+* StackTraceElement.NativeMethod
+* StackTraceElement.FileName
+* StackTraceElement.LineNumber
+* StackTraceElement.Container
+* StackTraceElement.ContainerSeparator
+* StackTraceElement.UnknownSource
+* ExtraClassInfo.Inexact
+* ExtraClassInfo.Container
+* ExtraClassInfo.ContainerSeparator
+* ExtraClassInfo.Location
+* ExtraClassInfo.Version
+
+The values are names from JAnsi's
+https://fusesource.github.io/jansi/documentation/api/org/fusesource/jansi/AnsiRenderer.Code.html[Code]
+class like `blue`, `bg_red`, and so on (Log4j ignores case.)
+
+The special key `StyleMapName` can be set to one of the following
+predefined maps: `Spock`, `Kirk`.
+
+As with %throwable, the *%xEx{suffix(_pattern_)* conversion will add
+the output of _pattern_ to the output only if there is a throwable to
+print.
+
+|[[PatternPercentLiteral]] *%*
+|The sequence %% outputs a single percent sign.
+|===
+
+By default the relevant information is output as is. However, with the
+aid of format modifiers it is possible to change the minimum field
+width, the maximum field width and justification.
+
+The optional format modifier is placed between the percent sign and the
+conversion character.
+
+The first optional format modifier is the _left justification flag_
+which is just the minus (-) character. Then comes the optional _minimum
+field width_ modifier. This is a decimal constant that represents the
+minimum number of characters to output. If the data item requires fewer
+characters, it is padded on either the left or the right until the
+minimum width is reached. The default is to pad on the left (right
+justify) but you can specify right padding with the left justification
+flag. The padding character is space. If the data item is larger than
+the minimum field width, the field is expanded to accommodate the data.
+The value is never truncated.
+
+This behavior can be changed using the _maximum field width_ modifier
+which is designated by a period followed by a decimal constant. If the
+data item is longer than the maximum field, then the extra characters
+are removed from the _beginning_ of the data item and not from the end.
+For example, it the maximum field width is eight and the data item is
+ten characters long, then the first two characters of the data item are
+dropped. This behavior deviates from the printf function in C where
+truncation is done from the end.
+
+Truncation from the end is possible by appending a minus character right
+after the period. In that case, if the maximum field width is eight and
+the data item is ten characters long, then the last two characters of
+the data item are dropped.
+
+Below are various format modifier examples for the category conversion
+specifier.
+
+.Pattern Converters
+|===
+|Format modifier |left justify |minimum width |maximum width |comment
+
+|%20c
+|false
+|20
+|none
+|Left pad with spaces if the category name is
+less than 20 characters long.
+
+|%-20c
+|true
+|20
+|none
+|Right pad with spaces if the category name is
+less than 20 characters long.
+
+|%.30c
+|NA
+|none
+|30
+|Truncate from the beginning if the category name
+is longer than 30 characters.
+
+|%20.30c
+|false
+|20
+|30
+|Left pad with spaces if the category name is
+shorter than 20 characters. However, if category name is longer than 30
+characters, then truncate from the beginning.
+
+|%-20.30c
+|true
+|20
+|30
+|Right pad with spaces if the category name is
+shorter than 20 characters. However, if category name is longer than 30
+characters, then truncate from the beginning.
+
+|%-20.-30c
+|true
+|20
+|30
+|Right pad with spaces if the category name is
+shorter than 20 characters. However, if category name is longer than 30
+characters, then truncate from the end.
+|===
+
+[#enable-jansi]
+=== ANSI Styling on Windows
+
+ANSI escape sequences are supported natively on many platforms but are
+not by default on Windows. To enable ANSI support add the
+http://jansi.fusesource.org/[Jansi] jar to your application and set
+property `log4j.skipJansi` to `false`. This allows Log4j to use Jansi to
+add ANSI escape codes when writing to the console.
+
+NOTE: Prior to Log4j 2.10, Jansi was enabled by default. The fact that
+Jansi requires native code means that Jansi can only be loaded by a
+single class loader. For web applications this means the Jansi jar has
+to be in the web container's classpath. To avoid causing problems for
+web applications, Log4j will no longer automatically try to load Jansi
+without explicit configuration from Log4j 2.10 onward.
+
+=== Example Patterns
+
+==== Filtered Throwables
+
+This example shows how to filter out classes from unimportant packages
+in stack traces.
+
+[source,xml]
+----
+<properties>
+ <property name="filters">org.junit,org.apache.maven,sun.reflect,java.lang.reflect</property>
+</properties>
+...
+<PatternLayout pattern="%m%xEx{filters(${filters})}%n"/>
+----
+
+The result printed to the console will appear similar to:
+
+....
+Exception java.lang.IllegalArgumentException: IllegalArgument
+at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:72) [test-classes/:?]
+... suppressed 26 lines
+at $Proxy0.invoke(Unknown Source)} [?:?]
+... suppressed 3 lines
+Caused by: java.lang.NullPointerException: null pointer
+at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:71) ~[test-classes/:?]
+... 30 more
+....
+
+==== ANSI Styled
+
+The log level will be highlighted according to the event's log level.
+All the content that follows the level will be bright green.
+
+[source,xml]
+----
+<PatternLayout>
+ <pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern>
+</PatternLayout>
+----
+
+=== Pattern Selectors
+
+The PatternLayout can be configured with a PatternSelector to allow it
+to choose a pattern to use based on attributes of the log event or other
+factors. A PatternSelector will normally be configured with a
+defaultPattern attribute, which is used when other criteria don't match,
+and a set of PatternMatch elements that identify the various patterns
+that can be selected.
+
+[#MarkerPatternSelector]
+==== MarkerPatternSelector
+
+The MarkerPatternSelector selects patterns based on the Marker included
+in the log event. If the Marker in the log event is equal to or is an
+ancestor of the name specified on the PatternMatch key attribute, then
+the pattern specified on that PatternMatch element will be used.
+
+[source,xml]
+----
+<PatternLayout>
+ <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
+ <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
+ </MarkerPatternSelector>
+</PatternLayout>
+----
+
+[#ScriptPatternSelector]
+==== ScriptPatternSelector
+
+The ScriptPatternSelector executes a script as descibed in the
+link:../configuration.html#Scripts[Scripts] section of the Configuration
+chapter. The script is passed all the properties configured in the
+Properties section of the configuration, the StrSubstitutor used by the
+Confguration in the "substitutor" vairables, and the log event in the
+"logEvent" variable, and is expected to return the value of the
+PatternMatch key that should be used, or null if the default pattern
+should be used.
+
+[source,xml]
+----
+<PatternLayout>
+ <ScriptPatternSelector defaultPattern="[%-5level] %c{1.} %C{1.}.%M.%L %msg%n">
+ <Script name="BeanShellSelector" language="bsh"><![CDATA[
+ if (logEvent.getLoggerName().equals("NoLocation")) {
+ return "NoLocation";
+ } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
+ return "Flow";
+ } else {
+ return null;
+ }]]>
+ </Script>
+ <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
+ <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
+ </ScriptPatternSelector>
+</PatternLayout>
+----
+
+[#RFC5424Layout]
+== RFC5424 Layout
+
+As the name implies, the Rfc5424Layout formats LogEvents in accordance
+with http://tools.ietf.org/html/rfc5424[RFC 5424], the enhanced Syslog
+specification. Although the specification is primarily directed at
+sending messages via Syslog, this format is quite useful for other
+purposes since items are passed in the message as self-describing
+key/value pairs.
+
+.Rfc5424Layout Parameters
+[cols="1m,1,4"]
+|===
+|Parameter Name |Type |Description
+
+|appName
+|String
+|The value to use as the APP-NAME in the RFC 5424
+syslog record.
+
+|charset
+|String
+|The character set to use when converting the syslog
+String to a byte array. The String must be a valid
+http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
+If not specified, the default system Charset will be used.
+
+|enterpriseNumber
+|integer
+|The IANA enterprise number as described in
+http://tools.ietf.org/html/rfc5424#section-7.2.2[RFC 5424]
+
+|exceptionPattern
+|String
+|One of the conversion specifiers from
+PatternLayout that defines which ThrowablePatternConverter to use to
+format exceptions. Any of the options that are valid for those
+specifiers may be included. The default is to not include the Throwable
+from the event, if any, in the output.
+
+|facility
+|String
+|The facility is used to try to classify the message.
+The facility option must be set to one of "KERN", "USER", "MAIL",
+"DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV",
+"FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2",
+"LOCAL3", "LOCAL4", "LOCAL5", "LOCAL6", or "LOCAL7". These values may be
+specified as upper or lower case characters.
+
+|format
+|String
+|If set to "RFC5424" the data will be formatted in
+accordance with RFC 5424. Otherwise, it will be formatted as a BSD
+Syslog record. Note that although BSD Syslog records are required to be
+1024 bytes or shorter the SyslogLayout does not truncate them. The
+RFC5424Layout also does not truncate records since the receiver must
+accept records of up to 2048 bytes and may accept records that are
+longer.
+
+|id
+|String
+|The default structured data id to use when formatting
+according to RFC 5424. If the LogEvent contains a StructuredDataMessage
+the id from the Message will be used instead of this value.
+
+|includeMDC
+|boolean
+|Indicates whether data from the ThreadContextMap
+will be included in the RFC 5424 Syslog record. Defaults to true.
+
+|loggerFields
+|List of KeyValuePairs
+|Allows arbitrary PatternLayout
+patterns to be included as specified ThreadContext fields; no default
+specified. To use, include a <LoggerFields> nested element, containing
+one or more <KeyValuePair> elements. Each <KeyValuePair> must have a key
+attribute, which specifies the key name which will be used to identify
+the field within the MDC Structured Data element, and a value attribute,
+which specifies the PatternLayout pattern to use as the value.
+
+|mdcExcludes
+|String
+|A comma separated list of mdc keys that should be
+excluded from the LogEvent. This is mutually exclusive with the
+mdcIncludes attribute. This attribute only applies to RFC 5424 syslog
+records.
+
+|mdcIncludes
+|String
+|A comma separated list of mdc keys that should be
+included in the FlumeEvent. Any keys in the MDC not found in the list
+will be excluded. This option is mutually exclusive with the mdcExcludes
+attribute. This attribute only applies to RFC 5424 syslog records.
+
+|mdcRequired
+|String
+|A comma separated list of mdc keys that must be
+present in the MDC. If a key is not present a LoggingException will be
+thrown. This attribute only applies to RFC 5424 syslog records.
+
+|mdcPrefix
+|String
+|A string that should be prepended to each MDC key in
+order to distinguish it from event attributes. The default string is
+"mdc:". This attribute only applies to RFC 5424 syslog records.
+
+|mdcId
+|String
+|A required MDC ID. This attribute only applies to RFC 5424 syslog records.
+
+|messageId
+|String
+|The default value to be used in the MSGID field of RFC 5424 syslog records.
+
+|newLine
+|boolean
+|If true, a newline will be appended to the end of the syslog record. The default is false.
+
+|newLineEscape
+|String
+|String that should be used to replace newlines within the message text.
+|===
+
+[#SerializedLayout]
+== Serialized Layout
+
+The SerializedLayout simply serializes the LogEvent into a byte array
+using Java Serialization. The SerializedLayout accepts no parameters.
+
+This layout is deprecated since version 2.9. Java Serialization has
+inherent security weaknesses, using this layout is no longer
+recommended. An alternative layout containing the same information is
+link:#JSONLayout[JsonLayout], configured with `properties="true"`.
+
+[#SyslogLayout]
+== Syslog Layout
+
+The SyslogLayout formats the LogEvent as BSD Syslog records matching the
+same format used by Log4j 1.2.
+
+.SyslogLayout Parameters
+[cols="1m,1,4"]
+|===
+|Parameter Name |Type |Description
+
+|charset
+|String
+|The character set to use when converting the syslog
+String to a byte array. The String must be a valid
+http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
+If not specified, this layout uses UTF-8.
+
+|facility
+|String
+|The facility is used to try to classify the message.
+The facility option must be set to one of "KERN", "USER", "MAIL",
+"DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV",
+"FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2",
+"LOCAL3", "LOCAL4", "LOCAL5", "LOCAL6", or "LOCAL7". These values may be
+specified as upper or lower case characters.
+
+|newLine
+|boolean
+|If true, a newline will be appended to the end of the
+syslog record. The default is false.
+
+|newLineEscape
+|String
+|String that should be used to replace newlines
+within the message text.
+|===
+
+[#XMLLayout]
+== XML Layout
+
+Appends a series of `Event` elements as defined in the log4j.dtd.
+
+=== Complete well-formed XML vs. fragment XML
+
+If you configure `complete="true"`, the appender outputs a well-formed
+XML document where the default namespace is the Log4j namespace
+`"http://logging.apache.org/log4j/2.0/events"`. By default, with
+`complete="false"`, you should include the output as an _external
+entity_ in a separate file to form a well-formed XML document, in which
+case the appender uses `namespacePrefix` with a default of `"log4j"`.
+
+A well-formed XML document follows this pattern:
+
+[source,xml]
+----
+<Event xmlns="http://logging.apache.org/log4j/2.0/events"
+ level="INFO"
+ loggerName="HelloWorld"
+ endOfBatch="false"
+ thread="main"
+ loggerFqcn="org.apache.logging.log4j.spi.AbstractLogger"
+ threadId="1"
+ threadPriority="5">
+ <Instant epochSecond="1493121664" nanoOfSecond="118000000"/>
+ <Marker name="child">
+ <Parents>
+ <Marker name="parent">
+ <Parents>
+ <Marker name="grandparent"/>
+ </Parents>
+ </Marker>
+ </Parents>
+ </Marker>
+ <Message>Hello, world!</Message>
+ <ContextMap>
+ <item key="bar" value="BAR"/>
+ <item key="foo" value="FOO"/>
+ </ContextMap>
+ <ContextStack>
+ <ContextStackItem>one</ContextStackItem>
+ <ContextStackItem>two</ContextStackItem>
+ </ContextStack>
+ <Source
+ class="logtest.Main"
+ method="main"
+ file="Main.java"
+ line="29"/>
+ <Thrown commonElementCount="0" message="error message" name="java.lang.RuntimeException">
+ <ExtendedStackTrace>
+ <ExtendedStackTraceItem
+ class="logtest.Main"
+ method="main"
+ file="Main.java"
+ line="29"
+ exact="true"
+ location="classes/"
+ version="?"/>
+ </ExtendedStackTrace>
+ </Thrown>
+</Event>
+----
+
+If `complete="false"`, the appender does not write the XML processing
+instruction and the root element.
+
+=== Marker
+
+Markers are represented by a `Marker` element within the `Event`
+element. The `Marker` element appears only when a marker is used in the
+log message. The name of the marker's parent will be provided in the
+`parent` attribute of the `Marker` element.
+
+=== Pretty vs. compact XML
+
+By default, the XML layout is not compact (a.k.a. not "pretty") with
+`compact="false"`, which means the appender uses end-of-line characters
+and indents lines to format the XML. If `compact="true"`, then no
+end-of-line or indentation is used. Message content may contain, of
+course, end-of-lines.
+
+.XmlLayout Parameters
+[cols="1m,1,4"]
+|===
+|Parameter Name |Type |Description
+
+|charset
+|String
+|The character set to use when converting to a byte
+array. The value must be a valid
+https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
+If not specified, UTF-8 will be used.
+
+|compact
+|boolean
+|If true, the appender does not use end-of-lines and
+indentation. Defaults to false.
+
+|complete
+|boolean
+|If true, the appender includes the XML header and
+footer. Defaults to false.
+
+|properties
+|boolean
+|If true, the appender includes the thread context
+map in the generated XML. Defaults to false.
+
+|locationInfo
+|boolean
+a|If true, the appender includes the location information in the generated
+XML. Defaults to false.
+
+Generating link:#LocationInformation[location information] is an
+expensive operation and may impact performance. Use with caution.
+
+|includeStacktrace
+|boolean
+|If true, include full stacktrace of any logged
+https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html[Throwable]
+(optional, default to true).
+
+|stacktraceAsString
+|boolean
+|Whether to format the stacktrace as a
+string, and not a nested object (optional, defaults to false).
+
+|includeNullDelimiter
+|boolean
+|Whether to include NULL byte as
+delimiter after each event (optional, default to false).
+|===
+
+To include any custom field in the output, use following syntax:
+
+[source,xml]
+----
+<XmlLayout>
+ <KeyValuePair key="additionalField1" value="constant value"/>
+ <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
+</XmlLayout>
+----
+
+Custom fields are always last, in the order they are declared. The
+values support link:lookups.html[lookups].
+
+Additional link:../runtime-dependencies.html[runtime dependencies] are
+required for using XmlLayout.
+
+[#YamlLayout]
+== YAML Layout
+
+Appends a series of YAML events as strings serialized as bytes.
+
+A YAML log event follows this pattern:
+
+[source,yaml]
+----
+---
+instant:
+ epochSecond: 1493121664
+ nanoOfSecond: 118000000
+thread: "main"
+level: "INFO"
+loggerName: "HelloWorld"
+marker:
+ name: "child"
+ parents:
+ - name: "parent"
+ parents:
+ - name: "grandparent"
+message: "Hello, world!"
+thrown:
+ commonElementCount: 0
+ message: "error message"
+ name: "java.lang.RuntimeException"
+ extendedStackTrace:
+ - class: "logtest.Main"
+ method: "main"
+ file: "Main.java"
+ line: 29
+ exact: true
+ location: "classes/"
+ version: "?"
+contextStack:
+- "one"
+- "two"
+endOfBatch: false
+loggerFqcn: "org.apache.logging.log4j.spi.AbstractLogger"
+contextMap:
+ bar: "BAR"
+ foo: "FOO"
+threadId: 1
+threadPriority: 5
+source:
+ class: "logtest.Main"
+ method: "main"
+ file: "Main.java"
+ line: 29
+----
+
+.YamlLayout Parameters
+[cols="1m,1,4"]
+|===
+|Parameter Name |Type |Description
+
+|charset
+|String
+|The character set to use when converting to a byte
+array. The value must be a valid
+https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[Charset].
+If not specified, UTF-8 will be used.
+
+|properties
+|boolean
+|If true, the appender includes the thread context
+map in the generated YAML. Defaults to false.
+
+|locationInfo
+|boolean
+a|
+If true, the appender includes the location information in the generated
+YAML. Defaults to false.
+
+Generating link:#LocationInformation[location information] is an
+expensive operation and may impact performance. Use with caution.
+
+|includeStacktrace
+|boolean
+|If true, include full stacktrace of any
+logged
+https://docs.oracle.com/javase/6/docs/api/java/lang/Throwable.html[Throwable]
+(optional, default to true).
+
+|stacktraceAsString
+|boolean
+|Whether to format the stacktrace as a
+string, and not a nested object (optional, defaults to false).
+
+|includeNullDelimiter
+|boolean
+|Whether to include NULL byte as
+delimiter after each event (optional, default to false).
+|===
+
+To include any custom field in the output, use following syntax:
+
+[source,xml]
+----
+<YamlLayout>
+ <KeyValuePair key="additionalField1" value="constant value"/>
+ <KeyValuePair key="additionalField2" value="$${ctx:key}"/>
+</YamlLayout>
+----
+
+Custom fields are always last, in the order they are declared. The
+values support link:lookups.html[lookups].
+
+Additional link:../runtime-dependencies.html[runtime dependencies] are
+required for using YamlLayout.
+
+[#LocationInformation]
+== Location Information
+
+If one of the layouts is configured with a location-related attribute
+like HTML link:#HtmlLocationInfo[locationInfo], or one of the patterns
+link:#PatternClass[%C or %class], link:#PatternFile[%F or %file],
+link:#PatternLocation[%l or %location], link:#PatternLine[%L or %line],
+link:#PatternMethod[%M or %method], Log4j will take a snapshot of the
+stack, and walk the stack trace to find the location information.
+
+This is an expensive operation: 1.3 - 5 times slower for synchronous
+loggers. Synchronous loggers wait as long as possible before they take
+this stack snapshot. If no location is required, the snapshot will never
+be taken.
+
+However, asynchronous loggers need to make this decision before passing
+the log message to another thread; the location information will be lost
+after that point. The
+link:../performance.html#asyncLoggingWithLocation[performance impact] of
+taking a stack trace snapshot is even higher for asynchronous loggers:
+logging with location is 30-100 times slower than without location. For
+this reason, asynchronous loggers and asynchronous appenders do not
+include location information by default.
+
+You can override the default behaviour in your logger or asynchronous
+appender configuration by specifying `includeLocation="true"`.
[3/3] logging-log4j2 git commit: LOG4J2-1802: Add changelog entry
Posted by ma...@apache.org.
LOG4J2-1802: Add changelog entry
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/ffd4ab63
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/ffd4ab63
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/ffd4ab63
Branch: refs/heads/master
Commit: ffd4ab638fc353cc67f22ee3957db56dbe8a2c17
Parents: f8e5094
Author: Matt Sicker <bo...@gmail.com>
Authored: Sun Apr 8 21:16:05 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Sun Apr 8 21:16:05 2018 -0500
----------------------------------------------------------------------
src/changes/changes.xml | 3 +++
1 file changed, 3 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/ffd4ab63/src/changes/changes.xml
----------------------------------------------------------------------
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 62c2412..ad7e632 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -31,6 +31,9 @@
- "remove" - Removed
-->
<release version="3.0.0" date="2018-xx-xx" description="GA Release 3.0.0">
+ <action issue="LOG4J2-1802" dev="mattsicker" type="add">
+ Convert documentation into AsciiDoc format.
+ </action>
<action issue="LOG4J2-2268" dev="rgoers" type="fix" due-to="Tilman Hausherr">
Improve plugin error message when elements are missing.
</action>