| <?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> |
| <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> |
| <tr> |
| <td>messagePattern</td> |
| <td>String</td> |
| <td>The pattern to use to format the String. If not supplied only the text derived from the logging |
| message will be used. See <a href="#PatternLayout">PatternLayout</a> for information on the pattern |
| strings.</td> |
| </tr> |
| <tr> |
| <td>threadContextExcludes</td> |
| <td>String</td> |
| <td>A comma separated list of ThreadContext attributes to exclude when formatting the event. This |
| attribute only applies when includeThreadContext="true" is specified. If threadContextIncludes |
| are also specified this attribute will be ignored.</td> |
| </tr> |
| <tr> |
| <td>threadContextIncludes</td> |
| <td>String</td> |
| <td>A comma separated list of ThreadContext attributes to include when formatting the event. This |
| attribute only applies when includeThreadContext="true" is specified. If threadContextExcludes |
| are also specified this attribute will override them. ThreadContext fields specified here that |
| have no value will be omitted.</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 includeThreadContext="true" threadContextIncludes="loginId,requestId"> |
| <MessagePattern>%d %5p [%t] %c{1} %X{loginId, requestId} - %m%n</MessagePattern> |
| <KeyValuePair key="additionalField1" value="constant value"/> |
| <KeyValuePair key="additionalField2" value="${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> |
| The compact attribute determines whether the output will be "pretty" or not. The default value is "false", |
| which means the appender uses end-of-line characters and indents lines to format the text. If |
| <code>compact="true"</code>, then no end-of-line or indentation is used, which will cause the output |
| to take less space. Of course, the message content may contain, escaped end-of-lines. |
| </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>endOfLine</td> |
| <td>String</td> |
| <td> |
| If set, overrides the default end-of-line string. E.g. set it to "\n" and use with eventEol=true and compact=true |
| to have one record per line separated by "\n" instead of "\r\n". Defaults to null (i.e. not set). |
| </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>includeTimeMillis</td> |
| <td>boolean</td> |
| <td>If true, the timeMillis attribute is included in the Json payload instead of the instant. timeMillis |
| will contain the number of milliseconds since midnight, January 1, 1970 UTC.</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 <em>named</em> formats are:</p> |
| <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{ISO8601_OFFSET_DATE_TIME_HH}</td> |
| <td>2012-11-02'T'14:34:02,781-07</td> |
| </tr> |
| <tr> |
| <td>%d{ISO8601_OFFSET_DATE_TIME_HHMM}</td> |
| <td>2012-11-02'T'14:34:02,781-0700</td> |
| </tr> |
| <tr> |
| <td>%d{ISO8601_OFFSET_DATE_TIME_HHCMM}</td> |
| <td>2012-11-02'T'14:34:02,781-07:00</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{UNIX}</td> |
| <td>1351866842</td> |
| </tr> |
| <tr> |
| <td>%d{UNIX_MILLIS}</td> |
| <td>1351866842781</td> |
| </tr> |
| </table> |
| <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. |
| </p> |
| <p>You can define custom date formats:</p> |
| <table> |
| <tr> |
| <th>Pattern</th> |
| <th>Example</th> |
| </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> |
| </table> |
| <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. To use zeros as the padding character prepend |
| the <em>minimum field width</em> with a zero. |
| </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 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>LevelPatternSelector</h5> |
| <p> |
| The LevelPatternSelector selects patterns based on the log level of |
| the log event. If the Level in the log event is equal to (ignoring case) |
| the name specified on the PatternMatch key attribute, then |
| the pattern specified on that PatternMatch element will be used. |
| </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" variables, and the |
| log event in the "logEvent" variable, and is expected to return the value of the PatternMatch key that |
| should be used, or null if the default pattern should be used. |
| </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="RFC5424 Layout"> |
| <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>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 <LoggerFields> nested element, containing one or more |
| <KeyValuePair> elements. Each <KeyValuePair> must have a key attribute, which |
| specifies the key name which will be used to identify the field within the MDC Structured Data element, |
| and a value attribute, which specifies the PatternLayout pattern to use as the value.</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="Serialized Layout"> |
| <p>The SerializedLayout simply serializes the LogEvent into a byte array using Java Serialization. |
| The SerializedLayout accepts no parameters. |
| </p> |
| <p> |
| This layout is deprecated since version 2.9. Java Serialization has inherent security weaknesses, |
| using this layout is no longer recommended. An alternative layout containing the same information |
| is <a href="#JSONLayout">JsonLayout</a>, configured with <code>properties="true"</code>. |
| </p> |
| </subsection> |
| <a name="SyslogLayout"/> |
| <subsection name="Syslog Layout"> |
| <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="XML Layout"> |
| <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"><Event xmlns="http://logging.apache.org/log4j/2.0/events" |
| level="INFO" |
| loggerName="HelloWorld" |
| endOfBatch="false" |
| thread="main" |
| loggerFqcn="org.apache.logging.log4j.spi.AbstractLogger" |
| threadId="1" |
| threadPriority="5"> |
| <Instant epochSecond="1493121664" nanoOfSecond="118000000"/> |
| <Marker name="child"> |
| <Parents> |
| <Marker name="parent"> |
| <Parents> |
| <Marker name="grandparent"/> |
| </Parents> |
| </Marker> |
| </Parents> |
| </Marker> |
| <Message>Hello, world!</Message> |
| <ContextMap> |
| <item key="bar" value="BAR"/> |
| <item key="foo" value="FOO"/> |
| </ContextMap> |
| <ContextStack> |
| <ContextStackItem>one</ContextStackItem> |
| <ContextStackItem>two</ContextStackItem> |
| </ContextStack> |
| <Source |
| class="logtest.Main" |
| method="main" |
| file="Main.java" |
| line="29"/> |
| <Thrown commonElementCount="0" message="error message" name="java.lang.RuntimeException"> |
| <ExtendedStackTrace> |
| <ExtendedStackTraceItem |
| class="logtest.Main" |
| method="main" |
| file="Main.java" |
| line="29" |
| exact="true" |
| location="classes/" |
| version="?"/> |
| </ExtendedStackTrace> |
| </Thrown> |
| </Event> |
| </pre> |
| <p> |
| If <code>complete="false"</code>, the appender does not write the XML processing instruction and the root |
| element. |
| </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. |
| </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> |
| <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> |
| <caption align="top">XmlLayout Parameters</caption> |
| </table> |
| <p> |
| To include any custom field in the output, use following syntax: |
| </p> |
| <pre class="prettyprint linenums"> |
| <XmlLayout> |
| <KeyValuePair key="additionalField1" value="constant value"/> |
| <KeyValuePair key="additionalField2" value="${dollar}${dollar}{ctx:key}"/> |
| </XmlLayout> |
| </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 XmlLayout. |
| </p> |
| </subsection> |
| <a name="YamlLayout"/> |
| <subsection name="YAML Layout"> |
| <p> |
| Appends a series of YAML events as strings serialized as bytes. |
| </p> |
| <p> |
| A YAML 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> |
| <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> |
| <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> |
| <caption align="top">YamlLayout Parameters</caption> |
| </table> |
| <p> |
| To include any custom field in the output, use following syntax: |
| </p> |
| <pre class="prettyprint linenums"> |
| <YamlLayout> |
| <KeyValuePair key="additionalField1" value="constant value"/> |
| <KeyValuePair key="additionalField2" value="${dollar}${dollar}{ctx:key}"/> |
| </YamlLayout> |
| </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 YamlLayout. |
| </p> |
| </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> |