<?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>
            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>
        </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 Graylog2 server:
          </p>
          <pre class="prettyprint linenums">
  &lt;Appenders&gt;
    &lt;Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201"&gt;
        &lt;GelfLayout host="someserver" compressionType="GZIP" compressionThreshold="1024"&gt;
            &lt;KeyValuePair key="additionalField1" value="constant value"/&gt;
            &lt;KeyValuePair key="additionalField2" value="${dollar}${dollar}{ctx:key}"/&gt;
        &lt;/GelfLayout&gt;
    &lt;/Socket&gt;
  &lt;/Appenders&gt;
</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>
            <caption align="top">GELF Layout Parameters</caption>
          </table>
           <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="HTMLLayout">
          <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>
            <caption align="top">HTML Layout Parameters</caption>
          </table>
        </subsection>
        <a name="JSONLayout"/>
        <subsection name="JSONLayout">
          <!-- From Javadoc of org.apache.logging.log4j.core.layout.JSONLayout -->
          <p>
          Appends a series of JSON events as strings serialized as bytes. This layout requires Jackson jar files
          (see pom.xml for details).
          </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>
          A well-formed JSON document follows this pattern:
          </p>
          <pre class="prettyprint linenums">[
  {
    "logger":"com.foo.Bar",
    "timestamp":"1376681196470",
    "level":"INFO",
    "threadId":1,
    "thread":"main",
    "threadPriority":1,
    "message":"Message flushed with immediate flush=true"
  },
  {
    "logger":"com.foo.Bar",
    "timestamp":"1376681196471",
    "level":"ERROR",
    "threadId":1,
    "thread":"main",
    "threadPriority":1,
    "message":"Message flushed with immediate flush=true",
    "throwable":"java.lang.IllegalArgumentException: badarg\\n\\tat org.apache.logging.log4j.core.appender.JSONCompleteFileAppenderTest.testFlushAtEndOfBatch(JSONCompleteFileAppenderTest.java:54)\\n\\tat sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)\\n\\tat sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)\\n\\tat sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)\\n\\tat java.lang.reflect.Method.invoke(Method.java:606)\\n\\tat org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:47)\\n\\tat org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12)\\n\\tat org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:44)\\n\\tat org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17)\\n\\tat org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:271)\\n\\tat org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:70)\\n\\tat org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:50)\\n\\tat org.junit.runners.ParentRunner$3.run(ParentRunner.java:238)\\n\\tat org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:63)\\n\\tat org.junit.runners.ParentRunner.runChildren(ParentRunner.java:236)\\n\\tat org.junit.runners.ParentRunner.access$000(ParentRunner.java:53)\\n\\tat org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:229)\\n\\tat org.junit.internal.runners.statements.RunBefores.evaluate(RunBefores.java:26)\\n\\tat org.junit.runners.ParentRunner.run(ParentRunner.java:309)\\n\\tat org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:50)\\n\\tat org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:38)\\n\\tat org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:467)\\n\\tat org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:683)\\n\\tat org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:390)\\n\\tat org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:197)\\n"
  }
]
</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>
          <p>
          This approach enforces the independence of the JSONLayout and the appender where you embed it.
          </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>
            <caption align="top">JSON Layout Parameters</caption>
          </table>
        </subsection>
        <a name="PatternLayout"/>
        <subsection name="PatternLayout">
          <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,781</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{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,781</td>
                    </tr>
                    <tr>
                      <td>%d{dd MMM yyyy HH:mm:ss,SSS}</td>
                      <td>02 Nov 2012 14:34:02,781</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>
              </td>
            </tr>
            <tr>
              <td align="center">
                <b>enc</b>{<i>pattern</i>}{[HTML|JSON]}<br />
                <b>encode</b>{<i>pattern</i>}{[HTML|JSON]}
              </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>&amp;, &lt;, &gt;, &quot;, &apos;, &#x2F;</td>
                    <td>Replaced with the corresponding HTML 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>&quot;</td>
                    <td>\&quot;</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>
              </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 />
                &nbsp;&nbsp;{["none"<br />
                &nbsp;&nbsp;|"full"<br />
                &nbsp;&nbsp;|depth<br />
                &nbsp;&nbsp;|"short"<br />
                &nbsp;&nbsp;|"short.className"<br />
                &nbsp;&nbsp;|"short.fileName"<br />
                &nbsp;&nbsp;|"short.lineNumber"<br />
                &nbsp;&nbsp;|"short.methodName"<br />
                &nbsp;&nbsp;|"short.message"<br />
                &nbsp;&nbsp;|"short.localizedMessage"]}<br />
                &nbsp;&nbsp;{suffix(<i>pattern</i>)}
                <!-- TODO: there are actually more options available in ThrowableFormatOptions that apply here -->
                <!-- separator(), filters(), and ansi() -->
              </td>
              <td>
                <p>
                  Outputs the Throwable trace bound to the LoggingEvent, by default this will output the full trace
                  as one would normally find with a call to Throwable.printStackTrace().
                </p>
                <p>
                  You can follow the throwable conversion word with an option in the form <b>%throwable{option}</b>.
                </p>
                <p>
                  <b>%throwable{short}</b> outputs the first line of the Throwable.
                </p>
                <p>
                  <b>%throwable{short.className}</b> outputs the name of the class where the exception occurred.
                </p>
                <p>
                  <b>%throwable{short.methodName}</b> outputs the method name where the exception occurred.
                </p>
                <p>
                  <b>%throwable{short.fileName}</b> outputs the name of the class where the exception occurred.
                </p>
                <p>
                  <b>%throwable{short.lineNumber}</b> outputs the line number where the exception occurred.
                </p>
                <p>
                  <b>%throwable{short.message}</b> outputs the message.
                </p>
                <p>
                  <b>%throwable{short.localizedMessage}</b> outputs the localized message.
                </p>
                <p>
                  <b>%throwable{n}</b> outputs the first n lines of the stack trace.
                </p>
                <p>
                  Specifying <b>%throwable{none}</b> or <b>%throwable{0}</b> suppresses output of the exception.
                </p>
                <p>
                  Specifying <b>%throwable{suffix{<i>pattern</i>}</b> adds the output of <i>pattern</i> to the
                  output only if there is a throwable to print. This option is orthogonal with the above
                  conversions.
                </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.
                </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.)
                </p>
                <p>
                  The default syntax for embedded ANSI codes is:
                </p>
                <pre class="prettyprint linenums">&#64;|<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">&#64;|green Hello|@</pre>
                <p>
                  To render the message <code>"Hello"</code> in bold and red, use:
                </p>
                <pre class="prettyprint linenums">&#64;|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="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>{["none"|"short"|"full"|depth]}{[filters(packages)]}{suffix(<i>pattern</i>)}<br />
                <b>rException</b>{["none"|"short"|"full"|depth]}{[filters(packages)]}{suffix(<i>pattern</i>)}<br />
                <b>rThrowable</b>{["none"|"short"|"full"|depth]}{[filters(packages)]}{suffix(<i>pattern</i>)}
                <!-- TODO: more options are available in ThrowableFormatOptions -->
                <!-- FIXME: these options are confusing! -->
              </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
                  <b>%rEx{short}</b>
                  which will only output the first line of the Throwable or <b>%rEx{n}</b> where
                  the first n lines of the stacktrace will be printed. The conversion word can also be
                  followed by "filters(packages)" where packages is a list of package names that should
                  be suppressed from stack traces. Specifying <b>%rEx{none}</b>
                  or <b>%rEx{0}</b> will suppress printing of the exception.
                </p>
                <p>
                  As with the %throwable conversion, using <b>rEx{suffix(<i>pattern</i>)</b> 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="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.
                  <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="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/>
                &nbsp;&nbsp;{<br/>
                &nbsp;&nbsp;&nbsp;&nbsp;["none"|"short"|"full"|depth]<br/>
                &nbsp;&nbsp;&nbsp;&nbsp;[,filters(package,package,...)]<br/>
                &nbsp;&nbsp;}<br/>
                &nbsp;&nbsp;{ansi(<br/>
                &nbsp;&nbsp;&nbsp;&nbsp;Key=Value,Value,...<br/>
                &nbsp;&nbsp;&nbsp;&nbsp;Key=Value,Value,...<br/>
                &nbsp;&nbsp;&nbsp;&nbsp;...)<br/>
                &nbsp;&nbsp;}<br/>
                &nbsp;&nbsp;{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
                  <b>%xEx{short}</b>
                  which will only output the first line of the Throwable or <b>%xEx{n}</b> where
                  the first n lines of the stacktrace will be printed. The conversion word can also be
                  followed by "filters(packages)" where packages is a comma-sepaarted list of package names that
                  should be suppressed from stack traces. Specifying <b>%xEx{none}</b>
                  or <b>%xEx{0}</b> will suppress printing of the exception.
                </p>
                <p>
                 The <code>ansi</code> option renders stack traces with ANSI escapes code using the JAnsi library.
                 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 prefedined 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>
          <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 simply add the <a href="http://jansi.fusesource.org/">Jansi</a> jar to your
            application and Log4j will automatically make use of it when writing to the console.
          </p>
          <h4>Example Patterns</h4>
          <h5>Filtered Throwables</h5>
          <p>This example shows how to filter out classes from unimportant packages in stack traces.
          </p>
          <pre class="prettyprint linenums"><![CDATA[<properties>
  <property name="filters">org.junit,org.apache.maven,sun.reflect,java.lang.reflect</property>
</properties>
...
<PatternLayout pattern="%m%xEx{filters(${dollar}{filters})}%n"/>]]></pre>
          <p>The result printed to the console will appear similar to:
          </p>
 #if ($isPDF)
          <pre>Exception java.lang.IllegalArgumentException: IllegalArgument
         at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.
              testException(ExtendedThrowableTest.java:72) [test-classes/:?]
         ... suppressed 26 lines
         at ${dollar}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</pre>
 #else
          <pre>Exception java.lang.IllegalArgumentException: IllegalArgument
at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:72) [test-classes/:?]
... suppressed 26 lines
at ${dollar}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</pre>
 #end
          <h5>ANSI Styled</h5>
          <p>The log level will be highlighted according to the event's log level. All the content that follows
            the level will be bright green.</p>
          <pre class="prettyprint linenums"><![CDATA[<PatternLayout>
  <pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern>
</PatternLayout>]]></pre>

        <h4>Pattern Selectors</h4>
        <p>
          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.
        </p>
          <h5>MarkerPatternSelector</h5>
          <p>
            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.
          </p>
          <pre class="prettyprint linenums"><![CDATA[<PatternLayout>
  <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
    <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
  </MarkerPatternSelector>
</PatternLayout>]]></pre>
          <h5>ScriptPatternSelector</h5>
          <p>
            The ScriptPatternSelector executes a script as descibed in the <a href="../configuration.html#Scripts">Scripts</a> 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.
          </p>
          <pre class="prettyprint linenums"><![CDATA[<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;
      }]]]]><![CDATA[>
    </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>]]></pre>
      </subsection>
        <a name="RFC5424Layout"/>
        <subsection name="RFC5424Layout">
          <p>As the name implies, the RFC5424Layout formats LogEvents in accordance with
            <a href="http://tools.ietf.org/html/rfc5424">RFC 5424</a>, 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.
          </p>
          <table>
            <tr>
              <th>Parameter Name</th>
              <th>Type</th>
              <th>Description</th>
            </tr>
            <tr>
              <td>appName</td>
              <td>String</td>
              <td>The value to use as the APP-NAME in the RFC 5424 syslog record.</td>
            </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, the default system Charset will be used.</td>
            </tr>
            <tr>
              <td>enterpriseNumber</td>
              <td>integer</td>
              <td>The IANA enterprise number as described in
                <a href="http://tools.ietf.org/html/rfc5424#section-7.2.2">RFC 5424</a></td>
            </tr>
            <tr>
              <td>exceptionPattern</td>
              <td>String</td>
              <td>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.</td>
            </tr>
            <tr>
              <td>facility</td>
              <td>String</td>
              <td>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.</td>
            </tr>
            <tr>
              <td>format</td>
              <td>String</td>
              <td>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.</td>
            </tr>
            <tr>
              <td>id</td>
              <td>String</td>
              <td>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.</td>
            </tr>
            <tr>
              <td>immediateFlush</td>
              <td>boolean</td>
              <td>When set to true, each write will be followed by a flush. This will guarantee the data is written
                to disk but could impact performance.</td>
            </tr>
            <tr>
              <td>includeMDC</td>
              <td>boolean</td>
              <td>Indicates whether data from the ThreadContextMap will be included in the RFC 5424 Syslog record.
                Defaults to true.</td>
            </tr>
            <tr>
              <td>loggerFields</td>
              <td>List of KeyValuePairs</td>
              <td>Allows arbitrary PatternLayout patterns to be included as specified ThreadContext fields; no default
                specified. To use, include a &lt;LoggerFields&gt; nested element, containing one or more
                &lt;KeyValuePair&gt; elements. Each &lt;KeyValuePair&gt; 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.</td>
            </tr>
            <tr>
              <td>mdcExcludes</td>
              <td>String</td>
              <td>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.</td>
            </tr>
            <tr>
              <td>mdcIncludes</td>
              <td>String</td>
              <td>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.</td>
            </tr>
            <tr>
              <td>mdcRequired</td>
              <td>String</td>
              <td>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.</td>
            </tr>
            <tr>
              <td>mdcPrefix</td>
              <td>String</td>
              <td>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.</td>
            </tr>
            <tr>
              <td>mdcId</td>
              <td>String</td>
              <td>A required MDC ID. This attribute only applies to RFC 5424 syslog records.</td>
            </tr>
            <tr>
              <td>messageId</td>
              <td>String</td>
              <td>The default value to be used in the MSGID field of RFC 5424 syslog records. </td>
            </tr>
            <tr>
              <td>newLine</td>
              <td>boolean</td>
              <td>If true, a newline will be appended to the end of the syslog record. The default is false.</td>
            </tr>
            <tr>
              <td>newLineEscape</td>
              <td>String</td>
              <td>String that should be used to replace newlines within the message text.</td>
            </tr>
            <caption align="top">RFC5424Layout Parameters</caption>
          </table>
        </subsection>
        <a name="SerializedLayout"/>
        <subsection name="SerializedLayout">
          <p>The SerializedLayout simply serializes the LogEvent into a byte array. This is useful when
            sending messages via JMS or via a Socket connection. The SerializedLayout accepts no parameters.
          </p>
        </subsection>
        <a name="SyslogLayout"/>
        <subsection name="SyslogLayout">
          <p>The SyslogLayout formats the LogEvent as BSD Syslog records matching the same format used by
            Log4j 1.2.
          </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 UTF-8.</td>
            </tr>
            <tr>
              <td>facility</td>
              <td>String</td>
              <td>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.</td>
            </tr>
            <tr>
              <td>newLine</td>
              <td>boolean</td>
              <td>If true, a newline will be appended to the end of the syslog record. The default is false.</td>
            </tr>
             <tr>
               <td>newLineEscape</td>
               <td>String</td>
               <td>String that should be used to replace newlines within the message text.</td>
             </tr>
             <caption align="top">SyslogLayout Parameters</caption>
          </table>
        </subsection>
        <a name="XMLLayout"/>
        <subsection name="XMLLayout">
          <!-- From Javadoc of org.apache.logging.log4j.core.layout.XMLLayout -->
          <p>
            <!-- FIXME: log4j.dtd link is broken -->
          Appends a series of <code>Event</code> elements as defined in the <a href="log4j.dtd">log4j.dtd</a>.
          </p>
          <h4>Complete well-formed XML vs. fragment XML</h4>
          <p>
          If you configure <code>complete="true"</code>, the appender outputs a well-formed XML document where the
          default namespace is the Log4j namespace <code>"http://logging.apache.org/log4j/2.0/events"</code>.  By default,
          with <code>complete="false"</code>, you should include the output as an <em>external entity</em> in a
          separate file to form a well-formed XML document, in which case the appender uses
          <code>namespacePrefix</code> with a default of <code>"log4j"</code>.
          </p>
          <p>
          A well-formed XML document follows this pattern:
          </p>
          <pre class="prettyprint linenums">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Events xmlns=&quot;http://logging.apache.org/log4j/2.0/events&quot;&gt;
  &lt;Event logger=&quot;com.foo.Bar&quot; timestamp=&quot;1373436580419&quot; level=&quot;INFO&quot; threadId=&quot;1&quot; thread=&quot;main&quot; threadPriority=&quot;1&quot;&gt;
    &lt;Message&gt;&lt;![CDATA[This is a log message 1]]&gt;&lt;/Message&gt;
    &lt;Marker parent=&quot;Parent Marker&quot;&gt;&lt;Child Marker&gt;&lt;/Marker&gt;
  &lt;/Event&gt;
  &lt;Event logger=&quot;com.foo.Baz&quot; timestamp=&quot;1373436580420&quot; level=&quot;INFO&quot; threadId=&quot;1&quot; thread=&quot;main&quot; threadPriority=&quot;1&quot;&gt;
    &lt;Message&gt;&lt;![CDATA[This is a log message 2]]&gt;&lt;/Message&gt;
    &lt;Marker&gt;&lt;The Marker Name&gt;&lt;/Marker&gt;
  &lt;/Event&gt;
&lt;/Events&gt;</pre>
          <p>
          If <code>complete="false"</code>, the appender does not write the XML processing instruction and the root
          element.
          </p>
          <p>
          This approach enforces the independence of the XMLLayout and the appender where you embed it.
          </p>
          <h4>Marker</h4>
          <p>Markers are represented by a <code>Marker</code> element within the <code>Event</code> element.
          The <code>Marker</code> element appears only when a marker is used in the log message. The name of the marker's
          parent will be provided in the <code>parent</code> attribute of the <code>Marker</code> element.
          Only the leaf marker is included, not the full hierarchy.
          </p>
          <h4>Pretty vs. compact XML</h4>
          <p>
          By default, the XML 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 XML. If
          <code>compact="true"</code>,  then no end-of-line or indentation is used. Message content may contain,
          of course, 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>complete</td>
              <td>boolean</td>
              <td>If true, the appender includes the XML header and footer. 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 XML. Defaults to false.</td>
            </tr>
            <tr>
              <td>locationInfo</td>
              <td>boolean</td>
              <td>
              <p>If true, the appender includes the location information in the generated XML. 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>
            <caption align="top">XML Layout Parameters</caption>
          </table>
        </subsection>
        <a name="YamlLayout"/>
        <subsection name="YamlLayout">
          <!-- From Javadoc of org.apache.logging.log4j.core.layout.YamlLayout -->
          <p>
            Appends a series of YAML events as strings serialized as bytes.
          </p>
          <p>
            A YAML log event follows this pattern:
          </p>
          <pre>---
timeMillis: 1
thread: "MyThreadName"
level: "DEBUG"
loggerName: "a.B"
marker:
  name: "Marker1"
  parents:
  - name: "ParentMarker1"
    parents:
    - name: "GrandMotherMarker"
    - name: "GrandFatherMarker"
  - name: "ParentMarker2"
message: "Msg"
thrown:
  commonElementCount: 0
  localizedMessage: "testIOEx"
  message: "testIOEx"
  name: "java.io.IOException"
  cause:
    commonElementCount: 27
    localizedMessage: "testNPEx"
    message: "testNPEx"
    name: "java.lang.NullPointerException"
    extendedStackTrace:
    - class: "org.apache.logging.log4j.core.layout.LogEventFixtures"
      method: "createLogEvent"
      file: "LogEventFixtures.java"
      line: 52
      exact: false
      location: "test-classes/"
      version: "?"
  extendedStackTrace:
  - class: "org.apache.logging.log4j.core.layout.LogEventFixtures"
    method: "createLogEvent"
    file: "LogEventFixtures.java"
    line: 55
    exact: true
    location: "test-classes/"
    version: "?"
  - class: "org.apache.logging.log4j.core.layout.YamlLayoutTest"
    method: "testAllFeatures"
    file: "YamlLayoutTest.java"
    line: 109
    exact: true
    location: "test-classes/"
    version: "?"
  - class: "org.apache.logging.log4j.core.layout.YamlLayoutTest"
    method: "testLocationOnCompactOffEventEolOffMdcOn"
    file: "YamlLayoutTest.java"
    line: 280
    exact: true
    location: "test-classes/"
    version: "?"

...

  suppressed:
  - commonElementCount: 0
    localizedMessage: "I am suppressed exception 1"
    message: "I am suppressed exception 1"
    name: "java.lang.IndexOutOfBoundsException"
    extendedStackTrace:
    - class: "org.apache.logging.log4j.core.layout.LogEventFixtures"
      method: "createLogEvent"
      file: "LogEventFixtures.java"
      line: 56
      exact: true
      location: "test-classes/"
      version: "?"
    - class: "org.apache.logging.log4j.core.layout.YamlLayoutTest"
      method: "testAllFeatures"
      file: "YamlLayoutTest.java"
      line: 109
      exact: true
      location: "test-classes/"
      version: "?"
    - class: "org.apache.logging.log4j.core.layout.YamlLayoutTest"
      method: "testLocationOnCompactOffEventEolOffMdcOn"
      file: "YamlLayoutTest.java"
      line: 280
      exact: true
      location: "test-classes/"
      version: "?"

...

  - commonElementCount: 0
    localizedMessage: "I am suppressed exception 2"
    message: "I am suppressed exception 2"
    name: "java.lang.IndexOutOfBoundsException"
    extendedStackTrace:
    - class: "org.apache.logging.log4j.core.layout.LogEventFixtures"
      method: "createLogEvent"
      file: "LogEventFixtures.java"
      line: 57
      exact: true
      location: "test-classes/"
      version: "?"
    - class: "org.apache.logging.log4j.core.layout.YamlLayoutTest"
      method: "testAllFeatures"
      file: "YamlLayoutTest.java"
      line: 109
      exact: true
      location: "test-classes/"
      version: "?"
    - class: "org.apache.logging.log4j.core.layout.YamlLayoutTest"
      method: "testLocationOnCompactOffEventEolOffMdcOn"
      file: "YamlLayoutTest.java"
      line: 280
      exact: true
      location: "test-classes/"
      version: "?"

...

contextStack:
- "stack_msg1"
- "stack_msg2"
endOfBatch: false
loggerFqcn: "f.q.c.n"
contextMap:
  MDC.B: "B_Value"
  MDC.A: "A_Value"
threadId: 1
threadPriority: 5
source:
  class: "org.apache.logging.log4j.core.layout.LogEventFixtures"
  method: "createLogEvent"
  file: "LogEventFixtures.java"
  line: 53</pre>
          <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>properties</td>
              <td>boolean</td>
              <td>If true, the appender includes the thread context map in the generated YAML. Defaults to false.</td>
            </tr>
            <tr>
              <td>locationInfo</td>
              <td>boolean</td>
              <td>
              <p>If true, the appender includes the location information in the generated YAML. 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>
            <caption align="top">YAML Layout Parameters</caption>
          </table>
        </subsection>
        <a name="LocationInformation"/>
        <subsection name="Location Information">
        <p>
			If one of the layouts is
			configured with a location-related attribute like
			HTML <a href="#HtmlLocationInfo">locationInfo</a>,
			or one of the patterns
			<a href="#PatternClass">%C or %class</a>,
			<a href="#PatternFile">%F or %file</a>,
			<a href="#PatternLocation">%l or %location</a>,
			<a href="#PatternLine">%L or %line</a>,
			<a href="#PatternMethod">%M or %method</a>,
			Log4j will take a snapshot of the
			stack, and walk the stack trace to find the location information.
			</p>
			<p>
			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.
			</p><p>
              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 <a href="../performance.html#asyncLoggingWithLocation">performance impact</a>
              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.
			</p><p>
			You can override the default behaviour in your logger
			or asynchronous appender configuration
			by specifying
			<tt>includeLocation="true"</tt>.
			</p>
			<p>
			</p>
        </subsection>
      </section>
    </body>
</document>
