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