"Fossies" - the Fresh Open Source Software Archive 
Member "apache-log4j-2.12.4-src/src/site/xdoc/manual/layouts.xml.vm" (20 Dec 2021, 112842 Bytes) of package /linux/misc/apache-log4j-2.12.4-src.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the last
Fossies "Diffs" side-by-side code changes report for "layouts.xml.vm":
2.19.0_vs_2.20.0.
1 <?xml version="1.0"?>
2 <!--
3 Licensed to the Apache Software Foundation (ASF) under one or more
4 contributor license agreements. See the NOTICE file distributed with
5 this work for additional information regarding copyright ownership.
6 The ASF licenses this file to You under the Apache License, Version 2.0
7 (the "License"); you may not use this file except in compliance with
8 the License. You may obtain a copy of the License at
9
10 http://www.apache.org/licenses/LICENSE-2.0
11
12 Unless required by applicable law or agreed to in writing, software
13 distributed under the License is distributed on an "AS IS" BASIS,
14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 See the License for the specific language governing permissions and
16 limitations under the License.
17 -->
18
19 <document>
20 <properties>
21 <title>Log4j 2 Layouts</title>
22 <author email="rgoers@apache.org">Ralph Goers</author>
23 <author email="ggregory@apache.org">Gary Gregory</author>
24 </properties>
25 #set($dollar = '$')
26 #set($sharp = '#')
27 #set($javadocRoot = 'http://docs.oracle.com/javase/6/docs/api')
28 #macro(javadoc $path $class)
29 <a class="javadoc" href="${javadocRoot}/${path}/${class}.html">${class}</a>
30 #end
31 #set($Charset = "<a class='javadoc' href='${javadocRoot}/java/nio/charset/Charset.html'>Charset</a>")
32 #if (!$alignedFileName)
33 #set ($isPDF = true)
34 #set ($break = '<br />')
35 #else
36 #set ($isPDF = false)
37 #set ($break = '')
38 #end
39 <body>
40 <section name="Layouts">
41 <p>An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be
42 consuming the log event. In Log4j 1.x and Logback Layouts were expected to transform an event into a
43 String. In Log4j 2 Layouts return a byte array. This allows the result of the Layout to be useful in
44 many more types of Appenders. However, this means you need to configure most Layouts with a ${Charset} to
45 ensure the byte array contains correct values.
46 </p>
47 <p>
48 The root class for layouts that use a Charset is <code>org.apache.logging.log4j.core.layout.AbstractStringLayout</code>
49 where the default is UTF-8. Each layout that extends <code>AbstractStringLayout</code>
50 can provide its own default. See each layout below.
51 </p>
52 <p>
53 A custom character encoder was added to Log4j 2.4.1 for the ISO-8859-1 and US-ASCII charsets,
54 to bring some of the performance improvements built-in to Java 8 to Log4j for use on Java 7.
55 For applications that log only ISO-8859-1 characters, specifying this charset will improve performance significantly.
56 </p>
57 <a name="CSVLayouts"/>
58 <subsection name="CSV Layouts">
59 <p>
60 This layout creates <a href="https://en.wikipedia.org/wiki/Comma-separated_values">Comma Separated Value (CSV)</a>
61 records and requires <a href="https://commons.apache.org/proper/commons-csv/">Apache Commons CSV</a> 1.4.
62 </p>
63 <p>
64 The CSV layout can be used in two ways: First, using <code>CsvParameterLayout</code> to log event parameters
65 to create a custom database, usually to a logger and file appender uniquely configured for this purpose.
66 Second, using <code>CsvLogEventLayout</code> to log events to create a database, as an alternative to using a
67 full DBMS or using a JDBC driver that supports the CSV format.
68 </p>
69 <p>
70 The <code>CsvParameterLayout</code> converts an event's parameters into a CSV record, ignoring the message.
71 To log CSV records, you can use the usual Logger methods <code>info()</code>, <code>debug()</code>, and so on:
72 </p>
73 <pre class="prettyprint linenums">
74 logger.info("Ignored", value1, value2, value3);
75 </pre>
76 <p>
77 Which will create the CSV record:
78 </p>
79 <pre class="prettyprint linenums">
80 value1, value2, value3
81 </pre>
82 <p>
83 Alternatively, you can use a <code>ObjectArrayMessage</code>, which only carries parameters:
84 </p>
85 <pre class="prettyprint linenums">
86 logger.info(new ObjectArrayMessage(value1, value2, value3));
87 </pre>
88 <p>
89 The layouts <code>CsvParameterLayout</code> and <code>CsvLogEventLayout</code> are configured with the following parameters:
90 </p>
91 <table>
92 <caption>CsvParameterLayout and CsvLogEventLayout</caption>
93 <tr>
94 <th>Parameter Name</th>
95 <th>Type</th>
96 <th>Description</th>
97 </tr>
98 <tr>
99 <td>format</td>
100 <td>String</td>
101 <td>
102 One of the predefined formats: <code>Default</code>, <code>Excel</code>, <code>MySQL</code>,
103 <code>RFC4180</code>, <code>TDF</code>.
104 See
105 <a href="https://commons.apache.org/proper/commons-csv/archives/1.4/apidocs/org/apache/commons/csv/CSVFormat.Predefined.html">CSVFormat.Predefined</a>.
106 </td>
107 </tr>
108 <tr>
109 <td>delimiter</td>
110 <td>Character</td>
111 <td>Sets the delimiter of the format to the specified character.</td>
112 </tr>
113 <tr>
114 <td>escape</td>
115 <td>Character</td>
116 <td>Sets the escape character of the format to the specified character.</td>
117 </tr>
118 <tr>
119 <td>quote</td>
120 <td>Character</td>
121 <td>Sets the quoteChar of the format to the specified character.</td>
122 </tr>
123 <tr>
124 <td>quoteMode</td>
125 <td>String</td>
126 <td>
127 Sets the output quote policy of the format to the specified value. One of: <code>ALL</code>,
128 <code>MINIMAL</code>, <code>NON_NUMERIC</code>, <code>NONE</code>.
129 </td>
130 </tr>
131 <tr>
132 <td>nullString</td>
133 <td>String</td>
134 <td>Writes null as the given nullString when writing records.</td>
135 </tr>
136 <tr>
137 <td>recordSeparator</td>
138 <td>String</td>
139 <td>Sets the record separator of the format to the specified String.</td>
140 </tr>
141 <tr>
142 <td>charset</td>
143 <td>Charset</td>
144 <td>The output Charset.</td>
145 </tr>
146 <tr>
147 <td>header</td>
148 <td>Sets the header to include when the stream is opened.</td>
149 <td>Desc.</td>
150 </tr>
151 <tr>
152 <td>footer</td>
153 <td>Sets the footer to include when the stream is closed.</td>
154 <td>Desc.</td>
155 </tr>
156 </table>
157 <p>
158 Logging as a CSV events looks like this:
159 </p>
160 <pre class="prettyprint linenums">
161 logger.debug("one={}, two={}, three={}", 1, 2, 3);
162 </pre>
163 <p>
164 Produces a CSV record with the following fields:
165 <ol>
166 <li>Time Nanos</li>
167 <li>Time Millis</li>
168 <li>Level</li>
169 <li>Thread ID</li>
170 <li>Thread Name</li>
171 <li>Thread Priority</li>
172 <li>Formatted Message</li>
173 <li>Logger FQCN</li>
174 <li>Logger Name</li>
175 <li>Marker</li>
176 <li>Thrown Proxy</li>
177 <li>Source</li>
178 <li>Context Map</li>
179 <li>Context Stack</li>
180 </ol>
181 </p>
182 <pre class="prettyprint linenums">
183 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),{},[]
184 </pre>
185 <p>
186 Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using CSV layouts.
187 </p>
188 </subsection>
189 <a name="GELFLayout"/>
190 <subsection name="GELF Layout">
191 <!-- From Javadoc of org.apache.logging.log4j.core.layout.GelfLayout -->
192 <p>
193 Lays out events in the Graylog Extended Log Format (GELF) 1.1.
194 </p>
195 <p>
196 This layout compresses JSON to GZIP or ZLIB (the <code>compressionType</code>) if log event data is larger than 1024 bytes
197 (the <code>compressionThreshold</code>). This layout does not implement chunking.
198 </p>
199 <p>
200 Configure as follows to send to a Graylog 2.x server with UDP:
201 </p>
202 <pre class="prettyprint linenums">
203 <Appenders>
204 <Socket name="Graylog" protocol="udp" host="graylog.domain.com" port="12201">
205 <GelfLayout host="someserver" compressionType="ZLIB" compressionThreshold="1024"/>
206 </Socket>
207 </Appenders>
208 </pre>
209 <p>
210 Configure as follows to send to a Graylog 2.x server with TCP:
211 </p>
212 <pre class="prettyprint linenums">
213 <Appenders>
214 <Socket name="Graylog" protocol="tcp" host="graylog.domain.com" port="12201">
215 <GelfLayout host="someserver" compressionType="OFF" includeNullDelimiter="true"/>
216 </Socket>
217 </Appenders>
218 </pre>
219 <table>
220 <tr>
221 <th>Parameter Name</th>
222 <th>Type</th>
223 <th>Description</th>
224 </tr>
225 <tr>
226 <td>host</td>
227 <td>String</td>
228 <td>The value of the <code>host</code> property (optional, defaults to local host name).</td>
229 </tr>
230 <tr>
231 <td>compressionType</td>
232 <td><code>GZIP</code>, <code>ZLIB</code> or <code>OFF</code></td>
233 <td>Compression to use (optional, defaults to <code>GZIP</code>)</td>
234 </tr>
235 <tr>
236 <td>compressionThreshold</td>
237 <td>int</td>
238 <td>Compress if data is larger than this number of bytes (optional, defaults to 1024)</td>
239 </tr>
240 <tr>
241 <td>includeStacktrace</td>
242 <td>boolean</td>
243 <td>Whether to include full stacktrace of logged Throwables (optional, default to true).
244 If set to false, only the class name and message of the #javadoc('java/lang', 'Throwable')
245 will be included.</td>
246 </tr>
247 <tr>
248 <td>includeThreadContext</td>
249 <td>boolean</td>
250 <td>Whether to include thread context as additional fields (optional, default to true).</td>
251 </tr>
252 <tr>
253 <td>includeNullDelimiter</td>
254 <td>boolean</td>
255 <td>Whether to include NULL byte as delimiter after each event (optional, default to false).
256 Useful for Graylog GELF TCP input. Cannot be used with compression.</td>
257 </tr>
258 <caption align="top">GelfLayout Parameters</caption>
259 </table>
260 <p>
261 To include any custom field in the output, use following syntax:
262 </p>
263 <pre class="prettyprint linenums">
264 <GelfLayout>
265 <KeyValuePair key="additionalField1" value="constant value"/>
266 <KeyValuePair key="additionalField2" value="${dollar}${dollar}{ctx:key}"/>
267 </GelfLayout>
268 </pre>
269 <p>
270 Custom fields are included in the order they are declared. The values support <a href="lookups.html">lookups</a>.
271 </p>
272 <p>
273 See also:
274 </p>
275 <ul>
276 <li>The <a href="http://docs.graylog.org/en/latest/pages/gelf.html#gelf">GELF specification</a></li>
277 </ul>
278 </subsection>
279 <a name="HTMLLayout"/>
280 <subsection name="HTML Layout">
281 <p>The HtmlLayout generates an HTML page and adds each LogEvent to a row in a table.
282 </p>
283 <table>
284 <tr>
285 <th>Parameter Name</th>
286 <th>Type</th>
287 <th>Description</th>
288 </tr>
289 <tr>
290 <td>charset</td>
291 <td>String</td>
292 <td>The character set to use when converting the HTML String to a byte array. The value must be
293 a valid ${Charset}. If not specified, this layout uses UTF-8.</td>
294 </tr>
295 <tr>
296 <td>contentType</td>
297 <td>String</td>
298 <td>The value to assign to the Content-Type header. The default is "text/html".</td>
299 </tr>
300 <tr>
301 <td>locationInfo</td>
302 <td>boolean</td>
303 <td>
304 <a name="HtmlLocationInfo" />
305 <p>If true, the filename and line number will be included in the HTML output. The default value is
306 false.</p>
307 <p>Generating <a href="#LocationInformation">location information</a>
308 is an expensive operation and may impact performance. Use with caution.</p>
309 </td>
310 </tr>
311 <tr>
312 <td>title</td>
313 <td>String</td>
314 <td>A String that will appear as the HTML title.</td>
315 </tr>
316 <tr>
317 <td>fontName</td>
318 <td>String</td>
319 <td>The <code>font-family</code> to use. The default is "arial,sans-serif".</td>
320 </tr>
321 <tr>
322 <td>fontSize</td>
323 <td>String</td>
324 <td>The <code>font-size</code> to use. The default is "small".</td>
325 </tr>
326 <caption align="top">HtmlLayout Parameters</caption>
327 </table>
328 </subsection>
329 <a name="JSONLayout"/>
330 <subsection name="JSON Layout">
331 <p>
332 Appends a series of JSON events as strings serialized as bytes.
333 </p>
334 <h4>Complete well-formed JSON vs. fragment JSON</h4>
335 <p>
336 If you configure <code>complete="true"</code>, the appender outputs a well-formed JSON document. By default,
337 with <code>complete="false"</code>, you should include the output as an <em>external file</em> in a
338 separate file to form a well-formed JSON document.
339 </p>
340 <p>
341 If <code>complete="false"</code>, the appender does not write the JSON open array character "[" at the start
342 of the document, "]" and the end, nor comma "," between records.
343 </p>
344 <p>
345 Log event follows this pattern:
346 </p>
347 <pre class="prettyprint linenums">{
348 "instant" : {
349 "epochSecond" : 1493121664,
350 "nanoOfSecond" : 118000000
351 },
352 "thread" : "main",
353 "level" : "INFO",
354 "loggerName" : "HelloWorld",
355 "marker" : {
356 "name" : "child",
357 "parents" : [ {
358 "name" : "parent",
359 "parents" : [ {
360 "name" : "grandparent"
361 } ]
362 } ]
363 },
364 "message" : "Hello, world!",
365 "thrown" : {
366 "commonElementCount" : 0,
367 "message" : "error message",
368 "name" : "java.lang.RuntimeException",
369 "extendedStackTrace" : [ {
370 "class" : "logtest.Main",
371 "method" : "main",
372 "file" : "Main.java",
373 "line" : 29,
374 "exact" : true,
375 "location" : "classes/",
376 "version" : "?"
377 } ]
378 },
379 "contextStack" : [ "one", "two" ],
380 "endOfBatch" : false,
381 "loggerFqcn" : "org.apache.logging.log4j.spi.AbstractLogger",
382 "contextMap" : {
383 "bar" : "BAR",
384 "foo" : "FOO"
385 },
386 "threadId" : 1,
387 "threadPriority" : 5,
388 "source" : {
389 "class" : "logtest.Main",
390 "method" : "main",
391 "file" : "Main.java",
392 "line" : 29
393 }
394 }</pre>
395 <p>
396 If <code>complete="false"</code>, the appender does not write the JSON open array character "[" at the start
397 of the document, "]" and the end, nor comma "," between records.
398 </p>
399 <h4>Pretty vs. compact JSON</h4>
400 <p>
401 By default, the JSON layout is not compact (a.k.a. not "pretty") with <code>compact="false"</code>, which
402 means the appender uses end-of-line characters and indents lines to format the text. If
403 <code>compact="true"</code>, then no end-of-line or indentation is used. Message content may contain,
404 of course, escaped end-of-lines.
405 </p>
406 <table>
407 <tr>
408 <th>Parameter Name</th>
409 <th>Type</th>
410 <th>Description</th>
411 </tr>
412 <tr>
413 <td>charset</td>
414 <td>String</td>
415 <td>The character set to use when converting to a byte array. The value must be a valid ${Charset}.
416 If not specified, UTF-8 will be used.</td>
417 </tr>
418 <tr>
419 <td>compact</td>
420 <td>boolean</td>
421 <td>If true, the appender does not use end-of-lines and indentation. Defaults to false.</td>
422 </tr>
423 <tr>
424 <td>eventEol</td>
425 <td>boolean</td>
426 <td>
427 If true, the appender appends an end-of-line after each record. Defaults to false.
428 Use with eventEol=true and compact=true to get one record per line.
429 </td>
430 </tr>
431 <tr>
432 <td>endOfLine</td>
433 <td>String</td>
434 <td>
435 If set, overrides the default end-of-line string. E.g. set it to "\n" and use with eventEol=true and compact=true
436 to have one record per line separated by "\n" instead of "\r\n". Defaults to null (i.e. not set).
437 </td>
438 </tr>
439 <tr>
440 <td>complete</td>
441 <td>boolean</td>
442 <td>If true, the appender includes the JSON header and footer, and comma between records. Defaults to false.</td>
443 </tr>
444 <tr>
445 <td>properties</td>
446 <td>boolean</td>
447 <td>If true, the appender includes the thread context map in the generated JSON. Defaults to false.</td>
448 </tr>
449 <tr>
450 <td>propertiesAsList</td>
451 <td>boolean</td>
452 <td>If true, the thread context map is included as a list of map entry objects, where each entry has
453 a "key" attribute (whose value is the key) and a "value" attribute (whose value is the value).
454 Defaults to false, in which case the thread context map is included as a simple map of key-value pairs.</td>
455 </tr>
456 <tr>
457 <td>locationInfo</td>
458 <td>boolean</td>
459 <td>
460 <p>If true, the appender includes the location information in the generated JSON. Defaults to false.</p>
461 <p>Generating <a href="#LocationInformation">location information</a>
462 is an expensive operation and may impact performance. Use with caution.</p>
463 </td>
464 </tr>
465 <tr>
466 <td>includeStacktrace</td>
467 <td>boolean</td>
468 <td>If true, include full stacktrace of any logged #javadoc('java/lang', 'Throwable') (optional, default to true).</td>
469 </tr>
470 <tr>
471 <td>stacktraceAsString</td>
472 <td>boolean</td>
473 <td>Whether to format the stacktrace as a string, and not a nested object (optional, defaults to false).</td>
474 </tr>
475 <tr>
476 <td>includeNullDelimiter</td>
477 <td>boolean</td>
478 <td>Whether to include NULL byte as delimiter after each event (optional, default to false).</td>
479 </tr>
480 <tr>
481 <td>objectMessageAsJsonObject</td>
482 <td>boolean</td>
483 <td>If true, ObjectMessage is serialized as JSON object to the "message" field of the output log. Defaults to false.</td>
484 </tr>
485 <caption align="top">JsonLayout Parameters</caption>
486 </table>
487 <p>
488 To include any custom field in the output, use following syntax:
489 </p>
490 <pre class="prettyprint linenums">
491 <JsonLayout>
492 <KeyValuePair key="additionalField1" value="constant value"/>
493 <KeyValuePair key="additionalField2" value="${dollar}${dollar}{ctx:key}"/>
494 </JsonLayout>
495 </pre>
496 <p>
497 Custom fields are always last, in the order they are declared. The values support <a href="lookups.html">lookups</a>.
498 </p>
499 <p>
500 Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using JsonLayout.
501 </p>
502 </subsection>
503 <a name="PatternLayout"/>
504 <subsection name="Pattern Layout">
505 <p>A flexible layout configurable with pattern string. The goal of this class is to format a LogEvent and
506 return the results. The format of the result depends on the <em>conversion pattern</em>.
507 </p>
508 <p>The conversion pattern is closely related to the conversion pattern of the printf function in C.
509 A conversion pattern is composed of literal text and format control expressions called
510 <em>conversion specifiers</em>.
511 </p>
512 <p><i>Note that any literal text, including <b>Special Characters</b>, may be included in the conversion
513 pattern.</i> Special Characters include <b>\t</b>, <b>\n</b>, <b>\r</b>, <b>\f</b>. Use <b>\\</b> to
514 insert a single backslash into the output.
515 </p>
516 <p>Each conversion specifier starts with a percent sign (%) and is followed by optional <em>format
517 modifiers</em> and a <em>conversion character</em>. The conversion character specifies the type of
518 data, e.g. category, priority, date, thread name. The format modifiers control such things as field width,
519 padding, left and right justification. The following is a simple example.
520 </p>
521 <p>Let the conversion pattern be <b>"%-5p [%t]: %m%n"</b> and assume that the Log4j environment was set to
522 use a PatternLayout. Then the statements
523 <pre>Logger logger = LogManager.getLogger("MyLogger");
524 logger.debug("Message 1");
525 logger.warn("Message 2");</pre>
526 would yield the output
527 <pre>DEBUG [main]: Message 1
528 WARN [main]: Message 2</pre>
529 </p>
530 <p>Note that there is no explicit separator between text and conversion specifiers. The pattern parser
531 knows when it has reached the end of a conversion specifier when it reads a conversion character.
532 In the example above the conversion specifier <b>%-5p</b> means the priority of the logging event should
533 be left justified to a width of five characters.
534 </p>
535 <p>
536 If the pattern string does not contain a specifier to handle a Throwable being logged, parsing of the
537 pattern will act as if the "%xEx" specifier had be added to the end of the string. To suppress
538 formatting of the Throwable completely simply add "%ex{0}" as a specifier in the pattern string.
539 </p>
540 <table>
541 <tr>
542 <th>Parameter Name</th>
543 <th>Type</th>
544 <th>Description</th>
545 </tr>
546 <tr>
547 <td>charset</td>
548 <td>String</td>
549 <td>The character set to use when converting the syslog String to a byte array. The String must be
550 a valid ${Charset}. If not specified, this layout uses the platform default character set.
551 </td>
552 </tr>
553 <tr>
554 <td>pattern</td>
555 <td>String</td>
556 <td>A composite pattern string of one or more conversion patterns from the table below. Cannot be
557 specified with a PatternSelector.</td>
558 </tr>
559 <tr>
560 <td>patternSelector</td>
561 <td>PatternSelector</td>
562 <td>A component that analyzes information in the LogEvent and determines which pattern should be
563 used to format the event. The pattern and patternSelector parameters are mutually exclusive.</td>
564 </tr>
565 <tr>
566 <td>replace</td>
567 <td>RegexReplacement</td>
568 <td>Allows portions of the resulting String to be replaced. If configured, the replace element must
569 specify the regular expression to match and the substitution. This performs a function similar to
570 the RegexReplacement converter but applies to the whole message while the converter only
571 applies to the String its pattern generates.
572 </td>
573 </tr>
574 <tr>
575 <td>alwaysWriteExceptions</td>
576 <td>boolean</td>
577 <td>If <code>true</code> (it is by default) exceptions are always written even if the pattern contains no
578 exception conversions. This means that if you do not include a way to output exceptions in your pattern,
579 the default exception formatter will be added to the end of the pattern. Setting this to
580 <code>false</code> disables this behavior and allows you to exclude exceptions from your pattern
581 output.</td>
582 </tr>
583 <tr>
584 <td>header</td>
585 <td>String</td>
586 <td>The optional header string to include at the top of each log file.</td>
587 </tr>
588 <tr>
589 <td>footer</td>
590 <td>String</td>
591 <td>The optional footer string to include at the bottom of each log file.</td>
592 </tr>
593 <tr>
594 <td>disableAnsi</td>
595 <td>boolean</td>
596 <td>If <code>true</code> (default is false), do not output ANSI escape codes.</td>
597 </tr>
598 <tr>
599 <td>noConsoleNoAnsi</td>
600 <td>boolean</td>
601 <td>If <code>true</code> (default is false) and <code>System.console()</code> is null, do not output ANSI escape codes.</td>
602 </tr>
603 <caption align="top">PatternLayout Parameters</caption>
604 </table>
605 <table>
606 <tr>
607 <th>Parameter Name</th>
608 <th>Type</th>
609 <th>Description</th>
610 </tr>
611 <tr>
612 <td>regex</td>
613 <td>String</td>
614 <td>A Java-compliant regular expression to match in the resulting string. See
615 #javadoc('java/util/regex', 'Pattern').</td>
616 </tr>
617 <tr>
618 <td>replacement</td>
619 <td>String</td>
620 <td>The string to replace any matched sub-strings with.</td>
621 </tr>
622 <caption align="top">RegexReplacement Parameters</caption>
623 </table>
624 <h4>Patterns</h4>
625 <p>The conversions that are provided with Log4j are:
626 </p>
627 <table>
628 <tr>
629 <th>Conversion Pattern</th>
630 <th>Description</th>
631 </tr>
632 <tr>
633 <td align="center">
634 <b>c</b>{precision}<br />
635 <b>logger</b>{precision}
636 </td>
637 <td>
638 <p>Outputs the name of the logger that published the logging event. The logger conversion
639 specifier can be optionally followed by <em>precision specifier</em>, which consists of a
640 decimal integer, or a pattern starting with a decimal integer.
641 </p>
642 <p>When the precision specifier is an integer value, it reduces the size of the logger name.
643 If the number is positive, the layout prints the corresponding number of rightmost logger
644 name components. If negative, the layout removes the corresponding number of leftmost logger
645 name components.
646 </p>
647 <p>
648 If the precision contains any non-integer characters, then the layout abbreviates the name
649 based on the pattern. If the precision integer is less than one, the layout still prints
650 the right-most token in full. By default, the layout prints the logger name in full.
651 </p>
652 <table>
653 <tr>
654 <th>Conversion Pattern</th>
655 <th>Logger Name</th>
656 <th>Result</th>
657 </tr>
658 <tr>
659 <td>%c{1}</td>
660 <td>org.apache.${break}commons.Foo</td>
661 <td>Foo</td>
662 </tr>
663 <tr>
664 <td>%c{2}</td>
665 <td>org.apache.${break}commons.Foo</td>
666 <td>commons.Foo</td>
667 </tr>
668 <tr>
669 <td>%c{10}</td>
670 <td>org.apache.${break}commons.Foo</td>
671 <td>org.apache.${break}commons.Foo</td>
672 </tr>
673 <tr>
674 <td>%c{-1}</td>
675 <td>org.apache.${break}commons.Foo</td>
676 <td>apache.${break}commons.Foo</td>
677 </tr>
678 <tr>
679 <td>%c{-2}</td>
680 <td>org.apache.${break}commons.Foo</td>
681 <td>${break}commons.Foo</td>
682 </tr>
683 <tr>
684 <td>%c{-10}</td>
685 <td>org.apache.${break}commons.Foo</td>
686 <td>org.apache.${break}commons.Foo</td>
687 </tr>
688 <tr>
689 <td>%c{1.}</td>
690 <td>org.apache.${break}commons.Foo</td>
691 <td>o.a.c.Foo</td>
692 </tr>
693 <tr>
694 <td>%c{1.1.~.~}</td>
695 <td>org.apache.${break}commons.test.${break}Foo</td>
696 <td>o.a.~.~.Foo</td>
697 </tr>
698 <tr>
699 <td>%c{.}</td>
700 <td>org.apache.${break}commons.test.${break}Foo</td>
701 <td>....Foo</td>
702 </tr>
703 </table>
704 </td>
705 </tr>
706 <tr>
707 <td align="center">
708 <a name="PatternClass" />
709 <b>C</b>{precision}<br />
710 <b>class</b>{precision}
711 </td>
712 <td>
713 <p>Outputs the fully qualified class name of the caller issuing the logging request.
714 This conversion specifier can be optionally followed by <em>precision specifier</em>, that
715 follows the same rules as the logger name converter.
716 </p>
717 <p>Generating the class name of the caller (<a href="#LocationInformation">location information</a>)
718 is an expensive operation and may impact performance. Use with caution.</p>
719 </td>
720 </tr>
721 <tr>
722 <td align="center">
723 <b>d</b>{pattern}<br />
724 <b>date</b>{pattern}
725 </td>
726 <td>
727 <p>Outputs the date of the logging event. The date conversion specifier may be
728 followed by a set of braces containing a date and time pattern string per
729 #javadoc('java/text', 'SimpleDateFormat').
730 </p>
731 <p>The predefined <em>named</em> formats are:</p>
732 <table>
733 <tr>
734 <th>Pattern</th>
735 <th>Example</th>
736 </tr>
737 <tr>
738 <td>%d{DEFAULT}</td>
739 <td>2012-11-02 14:34:02,123</td>
740 </tr>
741 <tr>
742 <td>%d{DEFAULT_MICROS}</td>
743 <td>2012-11-02 14:34:02,123456</td>
744 </tr>
745 <tr>
746 <td>%d{DEFAULT_NANOS}</td>
747 <td>2012-11-02 14:34:02,123456789</td>
748 </tr>
749 <tr>
750 <td>%d{ISO8601}</td>
751 <td>2012-11-02T14:34:02,781</td>
752 </tr>
753 <tr>
754 <td>%d{ISO8601_BASIC}</td>
755 <td>20121102T143402,781</td>
756 </tr>
757 <tr>
758 <td>%d{ISO8601_OFFSET_DATE_TIME_HH}</td>
759 <td>2012-11-02'T'14:34:02,781-07</td>
760 </tr>
761 <tr>
762 <td>%d{ISO8601_OFFSET_DATE_TIME_HHMM}</td>
763 <td>2012-11-02'T'14:34:02,781-0700</td>
764 </tr>
765 <tr>
766 <td>%d{ISO8601_OFFSET_DATE_TIME_HHCMM}</td>
767 <td>2012-11-02'T'14:34:02,781-07:00</td>
768 </tr>
769 <tr>
770 <td>%d{ABSOLUTE}</td>
771 <td>14:34:02,781</td>
772 </tr>
773 <tr>
774 <td>%d{ABSOLUTE_MICROS}</td>
775 <td>14:34:02,123456</td>
776 </tr>
777 <tr>
778 <td>%d{ABSOLUTE_NANOS}</td>
779 <td>14:34:02,123456789</td>
780 </tr>
781 <tr>
782 <td>%d{DATE}</td>
783 <td>02 Nov 2012 14:34:02,781</td>
784 </tr>
785 <tr>
786 <td>%d{COMPACT}</td>
787 <td>20121102143402781</td>
788 </tr>
789 <tr>
790 <td>%d{UNIX}</td>
791 <td>1351866842</td>
792 </tr>
793 <tr>
794 <td>%d{UNIX_MILLIS}</td>
795 <td>1351866842781</td>
796 </tr>
797 </table>
798 <p>You can also use a set of braces containing a time zone id per
799 <a class="javadoc" href="${javadocRoot}/java/util/TimeZone.html${sharp}getTimeZone(java.lang.String)">
800 java.util.TimeZone.getTimeZone</a>. If no date format specifier is given then the DEFAULT format is used.
801 </p>
802 <p>You can define custom date formats:</p>
803 <table>
804 <tr>
805 <th>Pattern</th>
806 <th>Example</th>
807 </tr>
808 <tr>
809 <td>%d{HH:mm:ss,SSS}</td>
810 <td>14:34:02,123</td>
811 </tr>
812 <tr>
813 <td>%d{HH:mm:ss,nnnn} to %d{HH:mm:ss,nnnnnnnnn}</td>
814 <td>14:34:02,1234 to 14:34:02,123456789</td>
815 </tr>
816 <tr>
817 <td>%d{dd MMM yyyy HH:mm:ss,SSS}</td>
818 <td>02 Nov 2012 14:34:02,123</td>
819 </tr>
820 <tr>
821 <td>%d{dd MMM yyyy HH:mm:ss,nnnn} to %d{dd MMM yyyy HH:mm:ss,nnnnnnnnn}</td>
822 <td>02 Nov 2012 14:34:02,1234 to 02 Nov 2012 14:34:02,123456789</td>
823 </tr>
824 <tr>
825 <td>%d{HH:mm:ss}{GMT+0}</td>
826 <td>18:34:02</td>
827 </tr>
828 </table>
829 <p>
830 %d{UNIX} outputs the UNIX time in seconds. %d{UNIX_MILLIS} outputs the UNIX time in milliseconds.
831 The UNIX time is the difference, in seconds for UNIX and in milliseconds for UNIX_MILLIS, between
832 the current time and midnight, January 1, 1970 UTC. While the time unit is milliseconds, the
833 granularity depends on the operating system
834 (<a href="http://msdn.microsoft.com/en-us/windows/hardware/gg463266.aspx">Windows</a>).
835 This is an efficient way to output the event time because only a conversion from long to String
836 takes place, there is no Date formatting involved.
837 </p>
838 <p>
839 Log4j 2.11 adds limited support for timestamps more precise than milliseconds when running on Java 9.
840 Note that not all
841 <a href="https://docs.oracle.com/javase/9/docs/api/java/time/format/DateTimeFormatter.html">DateTimeFormatter</a>
842 formats are supported.
843 Only timestamps in the formats mentioned in the table above may use the "nano-of-second"
844 pattern letter <code>n</code> instead of the "fraction-of-second" pattern letter <code>S</code>.
845 </p>
846 <p>
847 Users may revert back to a millisecond-precision clock when running on Java 9 by setting system property
848 <code>log4j2.Clock</code> to <code>SystemMillisClock</code>.
849 </p>
850 </td>
851 </tr>
852 <tr>
853 <td align="center">
854 <b>enc</b>{<i>pattern</i>}{[HTML|XML|JSON|CRLF]}<br />
855 <b>encode</b>{<i>pattern</i>}{[HTML|XML|JSON|CRLF]}
856 </td>
857 <td>
858 <p>
859 Encodes and escapes special characters suitable for output in specific markup languages.
860 By default, this encodes for HTML if only one option is specified. The second option is used to
861 specify which encoding format should be used. This converter is particularly useful for encoding
862 user provided data so that the output data is not written improperly or insecurely.
863 </p>
864 <p>
865 A typical usage would encode the message
866 <code>%enc{%m}</code>
867 but user input could come from other locations as well, such as the MDC
868 <code>%enc{%mdc{key}}</code>
869 </p>
870 <p>Using the HTML encoding format, the following characters are replaced:</p>
871 <table>
872 <tr>
873 <th>Character</th>
874 <th>Replacement</th>
875 </tr>
876 <tr>
877 <td>'\r', '\n'</td>
878 <td>Converted into escaped strings "\\r" and "\\n" respectively</td>
879 </tr>
880 <tr>
881 <td>&, <, >, ", ', /</td>
882 <td>Replaced with the corresponding HTML entity</td>
883 </tr>
884 </table>
885 <p>Using the XML encoding format, this follows the escaping rules specified by
886 <a href="https://www.w3.org/TR/xml/">the XML specification</a>:</p>
887 <table>
888 <tr>
889 <th>Character</th>
890 <th>Replacement</th>
891 </tr>
892 <tr>
893 <td>&, <, >, ", '</td>
894 <td>Replaced with the corresponding XML entity</td>
895 </tr>
896 </table>
897 <p>
898 Using the JSON encoding format, this follows the escaping rules specified by
899 <a href="https://www.ietf.org/rfc/rfc4627.txt">RFC 4627 section 2.5</a>:
900 </p>
901 <table>
902 <tr>
903 <th>Character</th>
904 <th>Replacement</th>
905 </tr>
906 <tr>
907 <td>U+0000 - U+001F</td>
908 <td>\u0000 - \u001F</td>
909 </tr>
910 <tr>
911 <td>Any other control characters</td>
912 <td>Encoded into its <code>\uABCD</code> equivalent escaped code point</td>
913 </tr>
914 <tr>
915 <td>"</td>
916 <td>\"</td>
917 </tr>
918 <tr>
919 <td>\</td>
920 <td>\\</td>
921 </tr>
922 </table>
923 <p>
924 For example, the pattern <code>{"message": "%enc{%m}{JSON}"}</code> could be used to output a
925 valid JSON document containing the log message as a string value.
926 </p>
927 <p>Using the CRLF encoding format, the following characters are replaced:</p>
928 <table>
929 <tr>
930 <th>Character</th>
931 <th>Replacement</th>
932 </tr>
933 <tr>
934 <td>'\r', '\n'</td>
935 <td>Converted into escaped strings "\\r" and "\\n" respectively</td>
936 </tr>
937 </table>
938 </td>
939 </tr>
940 <tr>
941 <td align="center">
942 <b>equals</b>{pattern}{test}{substitution}<br />
943 <b>equalsIgnoreCase</b>{pattern}{test}{substitution}
944 </td>
945 <td>
946 <p>Replaces occurrences of 'test', a string, with its replacement 'substitution' in the
947 string resulting from evaluation of the pattern. For example, "%equals{[%marker]}{[]}{}" will
948 replace '[]' strings produces by events without markers with an empty string.
949 </p>
950 <p>The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
951 </p>
952 </td>
953 </tr>
954 <tr>
955 <td align="center">
956 <b>ex</b>|<b>exception</b>|<b>throwable</b><br/>
957 {<br/>
958 [ "none"<br />
959 | "full"<br />
960 | depth<br />
961 | "short"<br />
962 | "short.className"<br />
963 | "short.fileName"<br />
964 | "short.lineNumber"<br />
965 | "short.methodName"<br />
966 | "short.message"<br />
967 | "short.localizedMessage"]<br />
968 }<br />
969 {filters(package,package,...)}<br/>
970 {suffix(<i>pattern</i>)}<br/>
971 {separator(<i>separator</i>)}<br/>
972 </td>
973 <td>
974 <p>
975 Outputs the Throwable trace bound to the logging event, by default this will output the full trace
976 as one would normally find with a call to <code>Throwable.printStackTrace()</code>.
977 </p>
978 <p>
979 You can follow the throwable conversion word with an option in the form <code>%throwable{option}</code>.
980 </p>
981 <p>
982 <code>%throwable{short}</code> outputs the first line of the Throwable.
983 </p>
984 <p>
985 <code>%throwable{short.className}</code> outputs the name of the class where the exception occurred.
986 </p>
987 <p>
988 <code>%throwable{short.methodName}</code> outputs the method name where the exception occurred.
989 </p>
990 <p>
991 <code>%throwable{short.fileName}</code> outputs the name of the class where the exception occurred.
992 </p>
993 <p>
994 <code>%throwable{short.lineNumber}</code> outputs the line number where the exception occurred.
995 </p>
996 <p>
997 <code>%throwable{short.message}</code> outputs the message.
998 </p>
999 <p>
1000 <code>%throwable{short.localizedMessage}</code> outputs the localized message.
1001 </p>
1002 <p>
1003 <code>%throwable{n}</code> outputs the first n lines of the stack trace.
1004 </p>
1005 <p>
1006 Specifying <code>%throwable{none}</code> or <code>%throwable{0}</code> suppresses output of the exception.
1007 </p>
1008 <p>
1009 Use <code>{filters(<i>packages</i>)}</code> where <i>packages</i> is a list of package names to
1010 suppress matching stack frames from stack traces.
1011 </p>
1012 <p>
1013 Use <code>{suffix(<i>pattern</i>)}</code> to add the output of <i>pattern</i> at the end of each stack frames.
1014 </p>
1015 <p>
1016 Use a <code>{separator(...)}</code> as the end-of-line string. For example: <code>separator(|)</code>.
1017 The default value is the <code>line.separator</code> system property, which is operating system dependent.
1018 </p>
1019 </td>
1020 </tr>
1021 <tr>
1022 <td align="center">
1023 <a name="PatternFile" />
1024 <b>F</b><br />
1025 <b>file</b>
1026 </td>
1027 <td><p>Outputs the file name where the logging request was issued.</p>
1028 <p>Generating the file information (<a href="#LocationInformation">location information</a>)
1029 is an expensive operation and may impact performance. Use with caution.</p>
1030 </td>
1031 </tr>
1032 <tr>
1033 <td align="center">
1034 <b>highlight</b>{pattern}{style}
1035 </td>
1036 <td>
1037 <p>Adds ANSI colors to the result of the enclosed pattern based on the current event's logging level.
1038 (See Jansi <a href="#enable-jansi">configuration</a>.)
1039 </p>
1040 <p>The default colors for each level are:
1041 <table>
1042 <tr>
1043 <th>Level</th>
1044 <th>ANSI color</th>
1045 </tr>
1046 <tr>
1047 <td>FATAL</td>
1048 <td>Bright red</td>
1049 </tr>
1050 <tr>
1051 <td>ERROR</td>
1052 <td>Bright red</td>
1053 </tr>
1054 <tr>
1055 <td>WARN</td>
1056 <td>Yellow</td>
1057 </tr>
1058 <tr>
1059 <td>INFO</td>
1060 <td>Green</td>
1061 </tr>
1062 <tr>
1063 <td>DEBUG</td>
1064 <td>Cyan</td>
1065 </tr>
1066 <tr>
1067 <td>TRACE</td>
1068 <td>Black (looks dark grey)</td>
1069 </tr>
1070 </table>
1071 </p>
1072 <p>The color names are ANSI names defined in the
1073 <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/pattern/AnsiEscape.html">AnsiEscape</a> class.
1074 </p>
1075 <p>The color and attribute names and are standard, but the exact shade, hue, or value.
1076 </p>
1077 <table>
1078 <caption>Color table</caption>
1079 <tbody>
1080 <tr>
1081 <th>Intensity Code</th>
1082 <th>0</th>
1083 <th>1</th>
1084 <th>2</th>
1085 <th>3</th>
1086 <th>4</th>
1087 <th>5</th>
1088 <th>6</th>
1089 <th>7</th>
1090 </tr>
1091 <tr>
1092 <th>Normal</th>
1093 <td style="background: black;color:white">Black</td>
1094 <td style="background: maroon;color:white">Red</td>
1095 <td style="background: green;color:white">Green</td>
1096 <td style="background: olive;color:white">Yellow</td>
1097 <td style="background: navy;color:white">Blue</td>
1098 <td style="background: purple;color:white">Magenta</td>
1099 <td style="background: teal;color:white">Cyan</td>
1100 <td style="background: silver;color:black">White</td>
1101 </tr>
1102 <tr>
1103 <th>Bright</th>
1104 <td style="background: gray;color:white">Black</td>
1105 <td style="background: red;color:black">Red</td>
1106 <td style="background: lime;color:black">Green</td>
1107 <td style="background: yellow;color:black">Yellow</td>
1108 <td style="background: blue;color:white">Blue</td>
1109 <td style="background: fuchsia;color:black">Magenta</td>
1110 <td style="background: cyan;color:black">Cyan</td>
1111 <td style="background: white;color:black">White</td>
1112 </tr>
1113 </tbody>
1114 </table>
1115 <p>You can use the default colors with:
1116 <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}</pre>
1117 </p>
1118 <p>You can override the default colors in the optional {style} option. For example:
1119 #if ($isPDF)
1120 <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}
1121 {FATAL=white, ERROR=red, WARN=blue, INFO=black,
1122 DEBUG=green, TRACE=blue}</pre>
1123 #else
1124 <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}{FATAL=white, ERROR=red, WARN=blue, INFO=black, DEBUG=green, TRACE=blue}</pre>
1125 #end
1126 </p>
1127 <p>You can highlight only the a portion of the log event:
1128 <pre>%d [%t] %highlight{%-5level: %msg%n%throwable}</pre>
1129 </p>
1130 <p>You can style one part of the message and highlight the rest the log event:
1131 #if ($isPDF)
1132 <pre>%style{%d [%t]}{black} %highlight{%-5level:
1133 %msg%n%throwable}</pre>
1134 #else
1135 <pre>%style{%d [%t]}{black} %highlight{%-5level: %msg%n%throwable}</pre>
1136 #end
1137 </p>
1138 #if ($isPDF)
1139 <!--PB-->
1140 #end
1141 <p>You can also use the STYLE key to use a predefined group of colors:
1142 #if ($isPDF)
1143 <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}
1144 {STYLE=Logback}</pre>
1145 #else
1146 <pre>%highlight{%d [%t] %-5level: %msg%n%throwable}{STYLE=Logback}</pre>
1147 #end
1148 The STYLE value can be one of:
1149 <table>
1150 <?dbfo keep-together="auto" ?>
1151 <tr>
1152 <th>Style</th>
1153 <th>Description</th>
1154 </tr>
1155 <tr>
1156 <td>Default</td>
1157 <td>See above</td>
1158 </tr>
1159 <tr>
1160 <td>Logback</td>
1161 <td>
1162 <table>
1163 <tr>
1164 <th>Level</th>
1165 <th>ANSI color</th>
1166 </tr>
1167 <tr>
1168 <td>FATAL</td>
1169 <td>Blinking bright red</td>
1170 </tr>
1171 <tr>
1172 <td>ERROR</td>
1173 <td>Bright red</td>
1174 </tr>
1175 <tr>
1176 <td>WARN</td>
1177 <td>Red</td>
1178 </tr>
1179 <tr>
1180 <td>INFO</td>
1181 <td>Blue</td>
1182 </tr>
1183 <tr>
1184 <td>DEBUG</td>
1185 <td>Normal</td>
1186 </tr>
1187 <tr>
1188 <td>TRACE</td>
1189 <td>Normal</td>
1190 </tr>
1191 </table>
1192 </td>
1193 </tr>
1194 </table>
1195 </p>
1196 </td>
1197 </tr>
1198 <tr>
1199 <td align="center">
1200 <a name="PatternMap"/>
1201 <b>K</b>{key}<br />
1202 <b>map</b>{key}<br />
1203 <b>MAP</b>{key}
1204 </td>
1205 <td>
1206 <p>Outputs the entries in a
1207 <a class="javadoc" href="../log4j-api/apidocs/org/apache/logging/log4j/message/MapMessage.html">MapMessage</a>,
1208 if one is present in the event. The <b>K</b> conversion character can be followed by the key
1209 for the map placed between braces, as in
1210 <b>%K{clientNumber}</b> where <code>clientNumber</code> is the key. The value in the Map
1211 corresponding to the key will be output. If no additional sub-option
1212 is specified, then the entire contents of the Map key value pair set
1213 is output using a format {{key1,val1},{key2,val2}}
1214 </p>
1215 </td>
1216 </tr>
1217 <tr>
1218 <td align="center">
1219 <a name="PatternLocation" />
1220 <b>l</b><br />
1221 <b>location</b>
1222 </td>
1223 <td>
1224 <p>Outputs location information of the caller which generated the logging event.
1225 </p>
1226 <p>The location information depends on the JVM implementation but usually consists of the fully
1227 qualified name of the calling method followed by the callers source the file name and line
1228 number between parentheses.
1229 </p>
1230 <p>Generating <a href="#LocationInformation">location information</a>
1231 is an expensive operation and may impact performance. Use with caution.</p>
1232 </td>
1233 </tr>
1234 <tr>
1235 <td align="center">
1236 <a name="PatternLine" />
1237 <b>L</b><br />
1238 <b>line</b>
1239 </td>
1240 <td><p>Outputs the line number from where the logging request
1241 was issued.</p>
1242 <p>Generating line number information (<a href="#LocationInformation">location information</a>)
1243 is an expensive operation and may impact performance. Use with caution.</p>
1244 </td>
1245 </tr>
1246 <tr>
1247 <td align="center">
1248 <a name="PatternMessage"/>
1249 <b>m</b>{nolookups}{ansi}<br />
1250 <b>msg</b>{nolookups}{ansi}<br />
1251 <b>message</b>{nolookups}{ansi}
1252 </td>
1253 <td>
1254 <p>
1255 Outputs the application supplied message associated with the logging event.
1256 </p>
1257 <!-- Copied and tweaked from Javadoc for org.apache.logging.log4j.core.pattern.JAnsiMessageRenderer -->
1258 <p>
1259 Add <code>{ansi}</code> to render messages with ANSI escape codes (requires JAnsi,
1260 see <a href="#enable-jansi">configuration</a>.)
1261 </p>
1262 <p>
1263 The default syntax for embedded ANSI codes is:
1264 </p>
1265 <pre class="prettyprint linenums">@|<em>code</em>(,<em>code</em>)* <em>text</em>|@</pre>
1266 <p>
1267 For example, to render the message <code>"Hello"</code> in green, use:
1268 </p>
1269 <pre class="prettyprint linenums">@|green Hello|@</pre>
1270 <p>
1271 To render the message <code>"Hello"</code> in bold and red, use:
1272 </p>
1273 <pre class="prettyprint linenums">@|bold,red Warning!|@</pre>
1274 <p>
1275 You can also define custom style names in the configuration with the syntax:
1276 </p>
1277 <pre class="prettyprint linenums">%message{ansi}{StyleName=value(,value)*( StyleName=value(,value)*)*}%n</pre>
1278 <p>
1279 For example:
1280 </p>
1281 <pre class="prettyprint linenums">%message{ansi}{WarningStyle=red,bold KeyStyle=white ValueStyle=blue}%n</pre>
1282 <p>
1283 The call site can look like this:
1284 </p>
1285 <pre class="prettyprint linenums">logger.info("@|KeyStyle {}|@ = @|ValueStyle {}|@", entry.getKey(), entry.getValue());</pre>
1286 <p>
1287 Use <code>{nolookups}</code> to log messages like <code>"${esc.d}{date:YYYY-MM-dd}"</code>
1288 without using any lookups. Normally calling <code>logger.info("Try ${esc.d}{date:YYYY-MM-dd}")</code>
1289 would replace the date template <code>${esc.d}{date:YYYY-MM-dd}</code> with an actual date.
1290 Using <code>nolookups</code> disables this feature and logs the message string untouched.
1291 </p>
1292 </td>
1293 </tr>
1294 <tr>
1295 <td align="center">
1296 <a name="PatternMethod" />
1297 <b>M</b><br />
1298 <b>method</b>
1299 </td>
1300 <td><p>Outputs the method name where the logging request was issued.</p>
1301 <p>Generating the method name of the caller (<a href="#LocationInformation">location information</a>)
1302 is an expensive operation and may impact performance. Use with caution.</p>
1303 </td>
1304 </tr>
1305 <tr>
1306 <td align="center">
1307 <a name="PatternMarker"/>
1308 <b>marker</b>
1309 </td>
1310 <td>The full name of the marker, including parents, if one is present.</td>
1311 </tr>
1312 <tr>
1313 <td align="center">
1314 <a name="PatternMarkerSimpleName"/>
1315 <b>markerSimpleName</b>
1316 </td>
1317 <td>The simple name of the marker (not including parents), if one is present.</td>
1318 </tr>
1319 <tr>
1320 <td align="center">
1321 <a name="PatternMaxLength"/>
1322 <b>maxLen</b><br/>
1323 <b>maxLength</b>
1324 </td>
1325 <td>
1326 <p>
1327 Outputs the result of evaluating the pattern and truncating the result. If the length is greater
1328 than 20, then the output will contain a trailing ellipsis. If the provided length is invalid, a
1329 default value of 100 is used.
1330 </p>
1331 <p>
1332 Example syntax: <code>%maxLen{%p: %c{1} - %m%notEmpty{ =>%ex{short}}}{160}</code> will be limited to
1333 160 characters with a trailing ellipsis. Another example: <code>%maxLen{%m}{20}</code> will be
1334 limited to 20 characters and no trailing ellipsis.
1335 </p>
1336 </td>
1337 </tr>
1338 <tr>
1339 <td align="center">
1340 <a name="PatternNewLine"/>
1341 <b>n</b>
1342 </td>
1343 <td>
1344 <p>Outputs the platform dependent line separator character or characters.
1345 </p>
1346 <p>This conversion character offers practically the same
1347 performance as using non-portable line separator strings such as
1348 "\n", or "\r\n". Thus, it is the preferred way of specifying a
1349 line separator.
1350 </p>
1351 </td>
1352 </tr>
1353 <tr>
1354 <td align="center">
1355 <a name="NanoTime" />
1356 <b>N</b><br />
1357 <b>nano</b>
1358 </td>
1359 <td><p>Outputs the result of <code>System.nanoTime()</code> at the time the log event was created.</p>
1360 </td>
1361 </tr>
1362 <tr>
1363 <td align="center">
1364 <a name="Process ID" />
1365 <b>pid</b>{[defaultValue]}<br />
1366 <b>processId</b>{[defaultValue]}
1367 </td>
1368 <td><p>Outputs the process ID if supported by the underlying platform. An optional default value may be
1369 specified to be shown if the platform does not support process IDs.</p>
1370 </td>
1371 </tr>
1372 <tr>
1373 <td align="center">
1374 <a name="VariablesNotEmpty" />
1375 <b>variablesNotEmpty</b>{pattern}<br />
1376 <b>varsNotEmpty</b>{pattern}<br />
1377 <b>notEmpty</b>{pattern}
1378 </td>
1379 <td>
1380 <p>
1381 Outputs the result of evaluating the pattern if and only if all variables in the pattern are not empty.
1382 </p>
1383 <p>
1384 For example:
1385 <pre>%notEmpty{[%marker]}</pre>
1386 </p>
1387 </td>
1388 </tr>
1389 <tr>
1390 <td align="center">
1391 <a name="PatternLevel"/>
1392 <b>p</b>|<b>level</b>{<em>level</em>=<em>label</em>, <em>level</em>=<em>label</em>, ...}
1393 <b>p</b>|<b>level</b>{length=<em>n</em>}
1394 <b>p</b>|<b>level</b>{lowerCase=<em>true</em>|<em>false</em>}
1395 </td>
1396 <td>
1397 <p>
1398 Outputs the level of the logging event. You provide a level name map in the form
1399 "level=value, level=value" where level is the name of the Level and value is the value that
1400 should be displayed instead of the name of the Level.
1401 </p>
1402 <p>
1403 For example:
1404 <pre>%level{WARN=Warning, DEBUG=Debug, ERROR=Error, TRACE=Trace, INFO=Info}</pre>
1405 </p>
1406 <p>
1407 Alternatively, for the compact-minded:
1408 <pre>%level{WARN=W, DEBUG=D, ERROR=E, TRACE=T, INFO=I}</pre>
1409 </p>
1410 <p>
1411 More succinctly, for the same result as above, you can define the length of the level label:
1412 <pre>%level{length=1}</pre>
1413 If the length is greater than a level name length, the layout uses the normal level name.
1414 </p>
1415 <p>
1416 You can combine the two kinds of options:
1417 <pre>%level{ERROR=Error, length=2}</pre>
1418 This give you the <code>Error</code> level name and all other level names of length 2.
1419 </p>
1420 <p>
1421 Finally, you can output lower-case level names (the default is upper-case):
1422 <pre>%level{lowerCase=true}</pre>
1423 </p>
1424 </td>
1425 </tr>
1426 <tr>
1427 <td align="center">
1428 <a name="PatternRelative"/>
1429 <b>r</b><br />
1430 <b>relative</b>
1431 </td>
1432 <td>Outputs the number of milliseconds elapsed since the JVM was started until the creation
1433 of the logging event.
1434 </td>
1435 </tr>
1436 <tr>
1437 <td align="center">
1438 <a name="PatternReplace"/>
1439 <b>replace</b>{pattern}{regex}{substitution}
1440 </td>
1441 <td>
1442 <p>Replaces occurrences of 'regex', a regular expression, with its replacement 'substitution' in the
1443 string resulting from evaluation of the pattern. For example, "%replace{%msg}{\s}{}" will remove
1444 all spaces contained in the event message.
1445 </p>
1446 <p>The pattern can be arbitrarily complex and in particular can contain multiple conversion keywords.
1447 For instance, "%replace{%logger %msg}{\.}{/}" will replace all dots in the logger or the message of
1448 the event with a forward slash.
1449 </p>
1450 </td>
1451 </tr>
1452 <tr>
1453 <td align="center">
1454 <a name="PatternException"/>
1455 <b>rEx</b>|<b>rException</b>|<b>rThrowable</b><br/>
1456 {<br/>
1457 ["none" | "short" | "full" | depth]<br/>
1458 [,filters(package,package,...)]<br/>
1459 [,separator(<i>separator</i>)]<br/>
1460 }<br/>
1461 {ansi(<br/>
1462 Key=Value,Value,...<br/>
1463 Key=Value,Value,...<br/>
1464 ...)<br/>
1465 }<br/>
1466 {suffix(<i>pattern</i>)}<br/>
1467 </td>
1468 <td>
1469 <p>
1470 The same as the %throwable conversion word but the stack trace is printed starting with the
1471 first exception that was thrown followed by each subsequent wrapping exception.
1472 </p>
1473 <p>
1474 The throwable conversion word can be followed by an option in the form
1475 <code>%rEx{short}</code> which will only output the first line of the Throwable or
1476 <code>%rEx{n}</code> where the first n lines of the stack trace will be printed.
1477 </p>
1478 <p>
1479 Specifying <code>%rEx{none}</code> or <code>%rEx{0}</code> will suppress printing of the exception.
1480 </p>
1481 <p>
1482 Use <code>filters(<i>packages</i>)</code> where <i>packages</i> is a list of package names to
1483 suppress matching stack frames from stack traces.
1484 </p>
1485 <p>
1486 Use a <code>separator</code> string to separate the lines of a stack trace. For example:
1487 <code>separator(|)</code>. The default value is the <code>line.separator</code> system property,
1488 which is operating system dependent.
1489 </p>
1490 <p>
1491 Use <code>rEx{suffix(<i>pattern</i>)</code> to add the output of <i>pattern</i> to the output only
1492 when there is a throwable to print.
1493 </p>
1494 </td>
1495 </tr>
1496 <tr>
1497 <td align="center">
1498 <a name="PatternSequenceNumber"/>
1499 <b>sn</b><br />
1500 <b>sequenceNumber</b>
1501 </td>
1502 <td>Includes a sequence number that will be incremented in every event. The counter is a
1503 static variable so will only be unique within applications that share the same converter Class
1504 object.</td>
1505 </tr>
1506 <tr>
1507 <td align="center">
1508 <a name="PatternStyle"/>
1509 <b>style</b>{pattern}{ANSI style}
1510 </td>
1511 <td>
1512 <p>Uses ANSI escape sequences to style the result of the enclosed pattern. The style can consist of
1513 a comma separated list of style names from the following table.
1514 (See Jansi <a href="#enable-jansi">configuration</a>.)
1515 <table>
1516 <tr>
1517 <th>Style Name</th>
1518 <th>Description</th>
1519 </tr>
1520 <tr>
1521 <td>Normal</td>
1522 <td>Normal display</td>
1523 </tr>
1524 <tr>
1525 <td>Bright</td>
1526 <td>Bold</td>
1527 </tr>
1528 <tr>
1529 <td>Dim</td>
1530 <td>Dimmed or faint characters</td>
1531 </tr>
1532 <tr>
1533 <td>Underline</td>
1534 <td>Underlined characters</td>
1535 </tr>
1536 <tr>
1537 <td>Blink</td>
1538 <td>Blinking characters</td>
1539 </tr>
1540 <tr>
1541 <td>Reverse</td>
1542 <td>Reverse video</td>
1543 </tr>
1544 <tr>
1545 <td>Hidden</td>
1546 <td></td>
1547 </tr>
1548 <tr>
1549 <td>Black or FG_Black</td>
1550 <td>Set foreground color to black</td>
1551 </tr>
1552 <tr>
1553 <td>Red or FG_Red</td>
1554 <td>Set foreground color to red</td>
1555 </tr>
1556 <tr>
1557 <td>Green or FG_Green</td>
1558 <td>Set foreground color to green</td>
1559 </tr>
1560 <tr>
1561 <td>Yellow or FG_Yellow</td>
1562 <td>Set foreground color to yellow</td>
1563 </tr>
1564 <tr>
1565 <td>Blue or FG_Blue</td>
1566 <td>Set foreground color to blue</td>
1567 </tr>
1568 <tr>
1569 <td>Magenta or FG_Magenta</td>
1570 <td>Set foreground color to magenta</td>
1571 </tr>
1572 <tr>
1573 <td>Cyan or FG_Cyan</td>
1574 <td>Set foreground color to cyan</td>
1575 </tr>
1576 <tr>
1577 <td>White or FG_White</td>
1578 <td>Set foreground color to white</td>
1579 </tr>
1580 <tr>
1581 <td>Default or FG_Default</td>
1582 <td>Set foreground color to default (white)</td>
1583 </tr>
1584 <tr>
1585 <td>BG_Black</td>
1586 <td>Set background color to black</td>
1587 </tr>
1588 <tr>
1589 <td>BG_Red</td>
1590 <td>Set background color to red</td>
1591 </tr>
1592 <tr>
1593 <td>BG_Green</td>
1594 <td>Set background color to green</td>
1595 </tr>
1596 <tr>
1597 <td>BG_Yellow</td>
1598 <td>Set background color to yellow</td>
1599 </tr>
1600 <tr>
1601 <td>BG_Blue</td>
1602 <td>Set background color to blue</td>
1603 </tr>
1604 <tr>
1605 <td>BG_Magenta</td>
1606 <td>Set background color to magenta</td>
1607 </tr>
1608 <tr>
1609 <td>BG_Cyan</td>
1610 <td>Set background color to cyan</td>
1611 </tr>
1612 <tr>
1613 <td>BG_White</td>
1614 <td>Set background color to white</td>
1615 </tr>
1616 </table>
1617 </p>
1618 <p>For example:
1619 <pre>%style{%d{ISO8601}}{black} %style{[%t]}{blue} %style{%-5level:}{yellow} %style{%msg%n%throwable}{green}</pre>
1620 </p>
1621 <p>You can also combine styles:
1622 <pre>%d %highlight{%p} %style{%logger}{bright,cyan} %C{1.} %msg%n</pre>
1623 </p>
1624 <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:
1625 <pre>%black{%d{ISO8601}} %blue{[%t]} %yellow{%-5level:} %green{%msg%n%throwable}</pre>
1626 </p>
1627 </td>
1628 </tr>
1629 <tr>
1630 <td align="center">
1631 <a name="PatternThreadId"/>
1632 <b>T</b><br />
1633 <b>tid</b><br />
1634 <b>threadId</b>
1635 </td>
1636 <td>Outputs the ID of the thread that generated the logging event.</td>
1637 </tr>
1638 <tr>
1639 <td align="center">
1640 <a name="PatternThreadName"/>
1641 <b>t</b><br />
1642 <b>tn</b><br />
1643 <b>thread</b><br />
1644 <b>threadName</b>
1645 </td>
1646 <td>Outputs the name of the thread that generated the logging event.</td>
1647 </tr>
1648 <tr>
1649 <td align="center">
1650 <a name="PatternThreadPriority"/>
1651 <b>tp</b><br />
1652 <b>threadPriority</b>
1653 </td>
1654 <td>Outputs the priority of the thread that generated the logging event.</td>
1655 </tr>
1656 <tr>
1657 <td align="center">
1658 <a name="PatternLoggerFqcn"/>
1659 <b>fqcn</b>
1660 </td>
1661 <td>Outputs the fully qualified class name of the logger.</td>
1662 </tr>
1663 <tr>
1664 <td align="center">
1665 <a name="EndOfBatch"/>
1666 <b>endOfBatch</b>
1667 </td>
1668 <td>Outputs the EndOfBatch status of the logging event, as "true" or "false".</td>
1669 </tr>
1670 <tr>
1671 <td align="center">
1672 <a name="PatternNDC"/>
1673 <b>x</b><br />
1674 <b>NDC</b>
1675 </td>
1676 <td>Outputs the Thread Context Stack (also known as the Nested Diagnostic Context or NDC)
1677 associated with the thread that generated the logging event.
1678 </td>
1679 </tr>
1680 <tr>
1681 <td align="center">
1682 <a name="PatternMDC"/>
1683 <b>X</b>{key[,key2...]}<br />
1684 <b>mdc</b>{key[,key2...]}<br />
1685 <b>MDC</b>{key[,key2...]}
1686 </td>
1687 <td>
1688 <p>Outputs the Thread Context Map (also known as the Mapped Diagnostic Context or MDC)
1689 associated with the thread that generated the logging event. The
1690 <b>X</b>
1691 conversion character can be followed by one or more keys for the
1692 map placed between braces, as in
1693 <b>%X{clientNumber}</b>
1694 where
1695 <code>clientNumber</code>
1696 is the key. The value in the MDC
1697 corresponding to the key will be output.</p>
1698 <p>If a list of keys are provided, such as <b>%X{name, number}</b>, then each key that is present in the
1699 ThreadContext will be output using the format {name=val1, number=val2}. The key/value pairs will be
1700 printed in the order they appear in the list.</p>
1701 <p>If no sub-options are specified then the entire contents of the MDC key value pair set
1702 is output using a format {key1=val1, key2=val2}. The key/value pairs will be printed in sorted order.
1703 </p>
1704 <p>See the
1705 <a class="javadoc" href="../log4j-api/apidocs/org/apache/logging/log4j/ThreadContext.html">ThreadContext</a>
1706 class for more details.
1707 </p>
1708 </td>
1709 </tr>
1710 <tr>
1711 <td align="center">
1712 <a name="PatternUUID"/>
1713 <b>u</b>{"RANDOM" | "TIME"}<br />
1714 <b>uuid</b>
1715 </td>
1716 <td>Includes either a random or a time-based UUID. The time-based UUID is a Type 1 UUID that can
1717 generate up to 10,000 unique ids per millisecond, will use the MAC address of each host, and to
1718 try to insure uniqueness across multiple JVMs and/or ClassLoaders on the same host a
1719 random number between 0 and 16,384 will be associated with each instance of the UUID generator
1720 Class and included in each time-based UUID generated. Because time-based UUIDs contain
1721 the MAC address and timestamp they should be used with care as they can cause a security
1722 vulnerability.
1723 </td>
1724 </tr>
1725 <tr>
1726 <td align="center">
1727 <a name="PatternExtendedException"/>
1728 <b>xEx</b>|<b>xException</b>|<b>xThrowable</b><br/>
1729 {<br/>
1730 ["none" | "short" | "full" | depth]<br/>
1731 [,filters(package,package,...)]<br/>
1732 [,separator(<i>separator</i>)]<br/>
1733 }<br/>
1734 {ansi(<br/>
1735 Key=Value,Value,...<br/>
1736 Key=Value,Value,...<br/>
1737 ...)<br/>
1738 }<br/>
1739 {suffix(<i>pattern</i>)}<br/>
1740 </td>
1741 <td>
1742 <p>The same as the %throwable conversion word but also includes class packaging information.
1743 </p>
1744 <p>
1745 At the end of each stack element of the exception, a string containing the name of the jar file
1746 that contains the class or the directory the class is located in and the "Implementation-Version"
1747 as found in that jar's manifest will be added. If the information is uncertain, then the class
1748 packaging data will be preceded by a tilde, i.e. the '~' character.
1749 </p>
1750 <p>The throwable conversion word can be followed by an option in the form
1751 <code>%xEx{short}</code>
1752 which will only output the first line of the Throwable or <code>%xEx{n}</code> where
1753 the first n lines of the stack trace will be printed. Specifying <code>%xEx{none}</code>
1754 or <code>%xEx{0}</code> will suppress printing of the exception.
1755 </p>
1756 <p>
1757 Use <code>filters(<i>packages</i>)</code> where <i>packages</i> is a list of package names to
1758 suppress matching stack frames from stack traces.
1759 </p>
1760 <p>
1761 Use a <code>separator</code> string to separate the lines of a stack trace. For example:
1762 <code>separator(|)</code>. The default value is the <code>line.separator</code> system property,
1763 which is operating system dependent.
1764 </p>
1765 <p>
1766 The <code>ansi</code> option renders stack traces with ANSI escapes code using the JAnsi library.
1767 (See <a href="#enable-jansi">configuration</a>.)
1768 Use <code>{ansi}</code> to use the default color mapping. You can specify your own mappings with
1769 <code>key=value</code> pairs. The keys are:
1770 </p>
1771 <ul>
1772 <li>Prefix</li>
1773 <li>Name</li>
1774 <li>NameMessageSeparator</li>
1775 <li>Message</li>
1776 <li>At</li>
1777 <li>CauseLabel</li>
1778 <li>Text</li>
1779 <li>More</li>
1780 <li>Suppressed</li>
1781 <li>StackTraceElement.ClassName</li>
1782 <li>StackTraceElement.ClassMethodSeparator</li>
1783 <li>StackTraceElement.MethodName</li>
1784 <li>StackTraceElement.NativeMethod</li>
1785 <li>StackTraceElement.FileName</li>
1786 <li>StackTraceElement.LineNumber</li>
1787 <li>StackTraceElement.Container</li>
1788 <li>StackTraceElement.ContainerSeparator</li>
1789 <li>StackTraceElement.UnknownSource</li>
1790 <li>ExtraClassInfo.Inexact</li>
1791 <li>ExtraClassInfo.Container</li>
1792 <li>ExtraClassInfo.ContainerSeparator</li>
1793 <li>ExtraClassInfo.Location</li>
1794 <li>ExtraClassInfo.Version</li>
1795 </ul>
1796 <p>
1797 The values are names from JAnsi's
1798 <a href="https://fusesource.github.io/jansi/documentation/api/org/fusesource/jansi/AnsiRenderer.Code.html">Code</a>
1799 class like <code>blue</code>, <code>bg_red</code>, and so on (Log4j ignores case.)
1800 </p>
1801 <p>
1802 The special key <code>StyleMapName</code> can be set to one of the following predefined maps:
1803 <code>Spock</code>, <code>Kirk</code>.
1804 </p>
1805 <p>
1806 As with %throwable, the <b>%xEx{suffix(<i>pattern</i>)</b> conversion will add the output of
1807 <i>pattern</i> to the output only if there is a throwable to print.
1808 </p>
1809 </td>
1810 </tr>
1811 <tr>
1812 <td align="center">
1813 <a name="PatternPercentLiteral"/>
1814 <b>%</b>
1815 </td>
1816 <td>The sequence %% outputs a single percent sign.
1817 </td>
1818 </tr>
1819 </table>
1820 <p>By default the relevant information is output as is. However,
1821 with the aid of format modifiers it is possible to change the
1822 minimum field width, the maximum field width and justification.
1823 </p>
1824 <p>The optional format modifier is placed between the percent sign
1825 and the conversion character.
1826 </p>
1827 <p>The first optional format modifier is the
1828 <em>left justification
1829 flag
1830 </em>
1831 which is just the minus (-) character. Then comes the
1832 optional
1833 <em>minimum field width</em>
1834 modifier. This is a decimal
1835 constant that represents the minimum number of characters to
1836 output. If the data item requires fewer characters, it is padded on
1837 either the left or the right until the minimum width is
1838 reached. The default is to pad on the left (right justify) but you
1839 can specify right padding with the left justification flag. The
1840 padding character is space. If the data item is larger than the
1841 minimum field width, the field is expanded to accommodate the
1842 data. The value is never truncated. To use zeros as the padding character prepend
1843 the <em>minimum field width</em> with a zero.
1844 </p>
1845 <p>This behavior can be changed using the
1846 <em>maximum field
1847 width
1848 </em>
1849 modifier which is designated by a period followed by a
1850 decimal constant. If the data item is longer than the maximum
1851 field, then the extra characters are removed from the
1852 <em>beginning</em>
1853 of the data item and not from the end. For
1854 example, it the maximum field width is eight and the data item is
1855 ten characters long, then the first two characters of the data item
1856 are dropped. This behavior deviates from the printf function in C
1857 where truncation is done from the end.
1858 </p>
1859 <p>Truncation from the end is possible by appending a minus character
1860 right after the period. In that case, if the maximum field width
1861 is eight and the data item is ten characters long, then the last
1862 two characters of the data item are dropped.
1863 </p>
1864 <p>Below are various format modifier examples for the category
1865 conversion specifier.
1866 </p>
1867 <table>
1868 <tr>
1869 <th>Format modifier</th>
1870 <th>left justify</th>
1871 <th>minimum width</th>
1872 <th>maximum width</th>
1873 <th>comment</th>
1874 </tr>
1875 <tr>
1876 <td align="center">%20c</td>
1877 <td align="center">false</td>
1878 <td align="center">20</td>
1879 <td align="center">none</td>
1880 <td>Left pad with spaces if the category name is less than 20
1881 characters long.
1882 </td>
1883 </tr>
1884 <tr>
1885 <td align="center">%-20c</td>
1886 <td align="center">true</td>
1887 <td align="center">20</td>
1888 <td align="center">none</td>
1889 <td>Right pad with
1890 spaces if the category name is less than 20 characters long.
1891 </td>
1892 </tr>
1893 <tr>
1894 <td align="center">%.30c</td>
1895 <td align="center">NA</td>
1896 <td align="center">none</td>
1897 <td align="center">30</td>
1898 <td>Truncate from the beginning if the category name is longer than 30
1899 characters.
1900 </td>
1901 </tr>
1902 <tr>
1903 <td align="center">%20.30c</td>
1904 <td align="center">false</td>
1905 <td align="center">20</td>
1906 <td align="center">30</td>
1907 <td>Left pad with spaces if the category name is shorter than 20
1908 characters. However, if category name is longer than 30 characters,
1909 then truncate from the beginning.
1910 </td>
1911 </tr>
1912 <tr>
1913 <td align="center">%-20.30c</td>
1914 <td align="center">true</td>
1915 <td align="center">20</td>
1916 <td align="center">30</td>
1917 <td>Right pad with spaces if the category name is shorter than 20
1918 characters. However, if category name is longer than 30 characters,
1919 then truncate from the beginning.
1920 </td>
1921 </tr>
1922 <tr>
1923 <td align="center">%-20.-30c</td>
1924 <td align="center">true</td>
1925 <td align="center">20</td>
1926 <td align="center">30</td>
1927 <td>Right pad with spaces if the category name is shorter than 20
1928 characters. However, if category name is longer than 30 characters,
1929 then truncate from the end.
1930 </td>
1931 </tr>
1932 <caption align="top">Pattern Converters</caption>
1933 </table>
1934 <a name="enable-jansi"></a>
1935 <h4>ANSI Styling on Windows</h4>
1936 <p>ANSI escape sequences are supported natively on many platforms but are not by default on Windows. To
1937 enable ANSI support add the <a href="http://jansi.fusesource.org/">Jansi</a> jar to your application
1938 and set property <code>log4j.skipJansi</code> to <code>false</code>.
1939 This allows Log4j to use Jansi to add ANSI escape codes when writing to the console.
1940 </p>
1941 <p>NOTE: Prior to Log4j 2.10, Jansi was enabled by default. The fact that Jansi requires native code
1942 means that Jansi can only be loaded by a single class loader. For web applications this means the
1943 Jansi jar has to be in the web container's classpath. To avoid causing problems for web applications,
1944 Log4j will no longer automatically try to load Jansi without explicit configuration from Log4j 2.10 onward.</p>
1945 <h4>Example Patterns</h4>
1946 <h5>Filtered Throwables</h5>
1947 <p>This example shows how to filter out classes from unimportant packages in stack traces.
1948 </p>
1949 <pre class="prettyprint linenums"><![CDATA[<properties>
1950 <property name="filters">org.junit,org.apache.maven,sun.reflect,java.lang.reflect</property>
1951 </properties>
1952 ...
1953 <PatternLayout pattern="%m%xEx{filters(${dollar}{filters})}%n"/>]]></pre>
1954 <p>The result printed to the console will appear similar to:
1955 </p>
1956 #if ($isPDF)
1957 <pre>Exception java.lang.IllegalArgumentException: IllegalArgument
1958 at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.
1959 testException(ExtendedThrowableTest.java:72) [test-classes/:?]
1960 ... suppressed 26 lines
1961 at ${dollar}Proxy0.invoke(Unknown Source)} [?:?]
1962 ... suppressed 3 lines
1963 Caused by: java.lang.NullPointerException: null pointer
1964 at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.
1965 testException(ExtendedThrowableTest.java:71) ~[test-classes/:?]
1966 ... 30 more</pre>
1967 #else
1968 <pre>Exception java.lang.IllegalArgumentException: IllegalArgument
1969 at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:72) [test-classes/:?]
1970 ... suppressed 26 lines
1971 at ${dollar}Proxy0.invoke(Unknown Source)} [?:?]
1972 ... suppressed 3 lines
1973 Caused by: java.lang.NullPointerException: null pointer
1974 at org.apache.logging.log4j.core.pattern.ExtendedThrowableTest.testException(ExtendedThrowableTest.java:71) ~[test-classes/:?]
1975 ... 30 more</pre>
1976 #end
1977 <h5>ANSI Styled</h5>
1978 <p>The log level will be highlighted according to the event's log level. All the content that follows
1979 the level will be bright green.</p>
1980 <pre class="prettyprint linenums"><![CDATA[<PatternLayout>
1981 <pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern>
1982 </PatternLayout>]]></pre>
1983
1984 <h4>Pattern Selectors</h4>
1985 <p>
1986 The PatternLayout can be configured with a PatternSelector to allow it to choose a pattern to use based on
1987 attributes of the log event or other factors. A PatternSelector will normally be configured with a defaultPattern
1988 attribute, which is used when other criteria don't match, and a set of PatternMatch elements that identify
1989 the various patterns that can be selected.
1990 </p>
1991 <h5>MarkerPatternSelector</h5>
1992 <p>
1993 The MarkerPatternSelector selects patterns based on the Marker included in the log event. If the Marker in
1994 the log event is equal to or is an ancestor of the name specified on the PatternMatch key attribute, then the
1995 pattern specified on that PatternMatch element will be used.
1996 </p>
1997 <pre class="prettyprint linenums"><![CDATA[<PatternLayout>
1998 <MarkerPatternSelector defaultPattern="[%-5level] %c{1.} %msg%n">
1999 <PatternMatch key="FLOW" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
2000 </MarkerPatternSelector>
2001 </PatternLayout>]]></pre>
2002 <h5>ScriptPatternSelector</h5>
2003 <p>
2004 The ScriptPatternSelector executes a script as descibed in the <a href="../configuration.html#Scripts">Scripts</a> section of the
2005 Configuration chapter. The script is passed all the properties configured in the Properties section of the
2006 configuration, the StrSubstitutor used by the Confguration in the "substitutor" vairables, and the
2007 log event in the "logEvent" variable, and is expected to return the value of the PatternMatch key that
2008 should be used, or null if the default pattern should be used.
2009 </p>
2010 <pre class="prettyprint linenums"><![CDATA[<PatternLayout>
2011 <ScriptPatternSelector defaultPattern="[%-5level] %c{1.} %C{1.}.%M.%L %msg%n">
2012 <Script name="BeanShellSelector" language="bsh"><![CDATA[
2013 if (logEvent.getLoggerName().equals("NoLocation")) {
2014 return "NoLocation";
2015 } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) {
2016 return "Flow";
2017 } else {
2018 return null;
2019 }]]]]><![CDATA[>
2020 </Script>
2021 <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
2022 <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ====== %C{1.}.%M:%L %msg ======%n"/>
2023 </ScriptPatternSelector>
2024 </PatternLayout>]]></pre>
2025 </subsection>
2026 <a name="RFC5424Layout"/>
2027 <subsection name="RFC5424 Layout">
2028 <p>As the name implies, the Rfc5424Layout formats LogEvents in accordance with
2029 <a href="http://tools.ietf.org/html/rfc5424">RFC 5424</a>, the enhanced Syslog specification. Although the specification
2030 is primarily directed at sending messages via Syslog, this format is quite useful for
2031 other purposes since items are passed in the message as self-describing key/value pairs.
2032 </p>
2033 <table>
2034 <tr>
2035 <th>Parameter Name</th>
2036 <th>Type</th>
2037 <th>Description</th>
2038 </tr>
2039 <tr>
2040 <td>appName</td>
2041 <td>String</td>
2042 <td>The value to use as the APP-NAME in the RFC 5424 syslog record.</td>
2043 </tr>
2044 <tr>
2045 <td>charset</td>
2046 <td>String</td>
2047 <td>The character set to use when converting the syslog String to a byte array. The String must be
2048 a valid ${Charset}. If not specified, the default system Charset will be used.</td>
2049 </tr>
2050 <tr>
2051 <td>enterpriseNumber</td>
2052 <td>integer</td>
2053 <td>The IANA enterprise number as described in
2054 <a href="http://tools.ietf.org/html/rfc5424#section-7.2.2">RFC 5424</a></td>
2055 </tr>
2056 <tr>
2057 <td>exceptionPattern</td>
2058 <td>String</td>
2059 <td>One of the conversion specifiers from PatternLayout that defines which ThrowablePatternConverter
2060 to use to format exceptions. Any of the options that are valid for those specifiers may be included.
2061 The default is to not include the Throwable from the event, if any, in the output.</td>
2062 </tr>
2063 <tr>
2064 <td>facility</td>
2065 <td>String</td>
2066 <td>The facility is used to try to classify the message. The facility option must be set to one of
2067 "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV",
2068 "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5",
2069 "LOCAL6", or "LOCAL7". These values may be specified as upper or lower case characters.</td>
2070 </tr>
2071 <tr>
2072 <td>format</td>
2073 <td>String</td>
2074 <td>If set to "RFC5424" the data will be formatted in accordance with RFC 5424. Otherwise, it will
2075 be formatted as a BSD Syslog record. Note that although BSD Syslog records are required to be
2076 1024 bytes or shorter the SyslogLayout does not truncate them. The RFC5424Layout also does not
2077 truncate records since the receiver must accept records of up to 2048 bytes and may accept records
2078 that are longer.</td>
2079 </tr>
2080 <tr>
2081 <td>id</td>
2082 <td>String</td>
2083 <td>The default structured data id to use when formatting according to RFC 5424. If the LogEvent contains
2084 a StructuredDataMessage the id from the Message will be used instead of this value.</td>
2085 </tr>
2086 <tr>
2087 <td>includeMDC</td>
2088 <td>boolean</td>
2089 <td>Indicates whether data from the ThreadContextMap will be included in the RFC 5424 Syslog record.
2090 Defaults to true.</td>
2091 </tr>
2092 <tr>
2093 <td>loggerFields</td>
2094 <td>List of KeyValuePairs</td>
2095 <td>Allows arbitrary PatternLayout patterns to be included as specified ThreadContext fields; no default
2096 specified. To use, include a <LoggerFields> nested element, containing one or more
2097 <KeyValuePair> elements. Each <KeyValuePair> must have a key attribute, which
2098 specifies the key name which will be used to identify the field within the MDC Structured Data element,
2099 and a value attribute, which specifies the PatternLayout pattern to use as the value.</td>
2100 </tr>
2101 <tr>
2102 <td>mdcExcludes</td>
2103 <td>String</td>
2104 <td>A comma separated list of mdc keys that should be excluded from the LogEvent. This is mutually
2105 exclusive with the mdcIncludes attribute. This attribute only applies to RFC 5424 syslog records.</td>
2106 </tr>
2107 <tr>
2108 <td>mdcIncludes</td>
2109 <td>String</td>
2110 <td>A comma separated list of mdc keys that should be included in the FlumeEvent. Any keys in the MDC
2111 not found in the list will be excluded. This option is mutually exclusive with the mdcExcludes
2112 attribute. This attribute only applies to RFC 5424 syslog records.</td>
2113 </tr>
2114 <tr>
2115 <td>mdcRequired</td>
2116 <td>String</td>
2117 <td>A comma separated list of mdc keys that must be present in the MDC. If a key is not present a
2118 LoggingException will be thrown. This attribute only applies to RFC 5424 syslog records.</td>
2119 </tr>
2120 <tr>
2121 <td>mdcPrefix</td>
2122 <td>String</td>
2123 <td>A string that should be prepended to each MDC key in order to distinguish it from event attributes.
2124 The default string is "mdc:". This attribute only applies to RFC 5424 syslog records.</td>
2125 </tr>
2126 <tr>
2127 <td>mdcId</td>
2128 <td>String</td>
2129 <td>A required MDC ID. This attribute only applies to RFC 5424 syslog records.</td>
2130 </tr>
2131 <tr>
2132 <td>messageId</td>
2133 <td>String</td>
2134 <td>The default value to be used in the MSGID field of RFC 5424 syslog records. </td>
2135 </tr>
2136 <tr>
2137 <td>newLine</td>
2138 <td>boolean</td>
2139 <td>If true, a newline will be appended to the end of the syslog record. The default is false.</td>
2140 </tr>
2141 <tr>
2142 <td>newLineEscape</td>
2143 <td>String</td>
2144 <td>String that should be used to replace newlines within the message text.</td>
2145 </tr>
2146 <caption align="top">Rfc5424Layout Parameters</caption>
2147 </table>
2148 </subsection>
2149 <a name="SerializedLayout"/>
2150 <subsection name="Serialized Layout">
2151 <p>The SerializedLayout simply serializes the LogEvent into a byte array using Java Serialization.
2152 The SerializedLayout accepts no parameters.
2153 </p>
2154 <p>
2155 This layout is deprecated since version 2.9. Java Serialization has inherent security weaknesses,
2156 using this layout is no longer recommended. An alternative layout containing the same information
2157 is <a href="#JSONLayout">JsonLayout</a>, configured with <code>properties="true"</code>.
2158 </p>
2159 </subsection>
2160 <a name="SyslogLayout"/>
2161 <subsection name="Syslog Layout">
2162 <p>The SyslogLayout formats the LogEvent as BSD Syslog records matching the same format used by
2163 Log4j 1.2.
2164 </p>
2165 <table>
2166 <tr>
2167 <th>Parameter Name</th>
2168 <th>Type</th>
2169 <th>Description</th>
2170 </tr>
2171 <tr>
2172 <td>charset</td>
2173 <td>String</td>
2174 <td>The character set to use when converting the syslog String to a byte array. The String must be
2175 a valid ${Charset}. If not specified, this layout uses UTF-8.</td>
2176 </tr>
2177 <tr>
2178 <td>facility</td>
2179 <td>String</td>
2180 <td>The facility is used to try to classify the message. The facility option must be set to one of
2181 "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV",
2182 "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5",
2183 "LOCAL6", or "LOCAL7". These values may be specified as upper or lower case characters.</td>
2184 </tr>
2185 <tr>
2186 <td>newLine</td>
2187 <td>boolean</td>
2188 <td>If true, a newline will be appended to the end of the syslog record. The default is false.</td>
2189 </tr>
2190 <tr>
2191 <td>newLineEscape</td>
2192 <td>String</td>
2193 <td>String that should be used to replace newlines within the message text.</td>
2194 </tr>
2195 <caption align="top">SyslogLayout Parameters</caption>
2196 </table>
2197 </subsection>
2198 <a name="XMLLayout"/>
2199 <subsection name="XML Layout">
2200 <p>
2201 <!-- FIXME: log4j.dtd link is broken -->
2202 Appends a series of <code>Event</code> elements as defined in the <a href="log4j.dtd">log4j.dtd</a>.
2203 </p>
2204 <h4>Complete well-formed XML vs. fragment XML</h4>
2205 <p>
2206 If you configure <code>complete="true"</code>, the appender outputs a well-formed XML document where the
2207 default namespace is the Log4j namespace <code>"http://logging.apache.org/log4j/2.0/events"</code>. By default,
2208 with <code>complete="false"</code>, you should include the output as an <em>external entity</em> in a
2209 separate file to form a well-formed XML document, in which case the appender uses
2210 <code>namespacePrefix</code> with a default of <code>"log4j"</code>.
2211 </p>
2212 <p>
2213 A well-formed XML document follows this pattern:
2214 </p>
2215 <pre class="prettyprint linenums"><Event xmlns="http://logging.apache.org/log4j/2.0/events"
2216 level="INFO"
2217 loggerName="HelloWorld"
2218 endOfBatch="false"
2219 thread="main"
2220 loggerFqcn="org.apache.logging.log4j.spi.AbstractLogger"
2221 threadId="1"
2222 threadPriority="5">
2223 <Instant epochSecond="1493121664" nanoOfSecond="118000000"/>
2224 <Marker name="child">
2225 <Parents>
2226 <Marker name="parent">
2227 <Parents>
2228 <Marker name="grandparent"/>
2229 </Parents>
2230 </Marker>
2231 </Parents>
2232 </Marker>
2233 <Message>Hello, world!</Message>
2234 <ContextMap>
2235 <item key="bar" value="BAR"/>
2236 <item key="foo" value="FOO"/>
2237 </ContextMap>
2238 <ContextStack>
2239 <ContextStackItem>one</ContextStackItem>
2240 <ContextStackItem>two</ContextStackItem>
2241 </ContextStack>
2242 <Source
2243 class="logtest.Main"
2244 method="main"
2245 file="Main.java"
2246 line="29"/>
2247 <Thrown commonElementCount="0" message="error message" name="java.lang.RuntimeException">
2248 <ExtendedStackTrace>
2249 <ExtendedStackTraceItem
2250 class="logtest.Main"
2251 method="main"
2252 file="Main.java"
2253 line="29"
2254 exact="true"
2255 location="classes/"
2256 version="?"/>
2257 </ExtendedStackTrace>
2258 </Thrown>
2259 </Event>
2260 </pre>
2261 <p>
2262 If <code>complete="false"</code>, the appender does not write the XML processing instruction and the root
2263 element.
2264 </p>
2265 <h4>Marker</h4>
2266 <p>Markers are represented by a <code>Marker</code> element within the <code>Event</code> element.
2267 The <code>Marker</code> element appears only when a marker is used in the log message. The name of the marker's
2268 parent will be provided in the <code>parent</code> attribute of the <code>Marker</code> element.
2269 </p>
2270 <h4>Pretty vs. compact XML</h4>
2271 <p>
2272 By default, the XML layout is not compact (a.k.a. not "pretty") with <code>compact="false"</code>, which
2273 means the appender uses end-of-line characters and indents lines to format the XML. If
2274 <code>compact="true"</code>, then no end-of-line or indentation is used. Message content may contain,
2275 of course, end-of-lines.
2276 </p>
2277 <table>
2278 <tr>
2279 <th>Parameter Name</th>
2280 <th>Type</th>
2281 <th>Description</th>
2282 </tr>
2283 <tr>
2284 <td>charset</td>
2285 <td>String</td>
2286 <td>The character set to use when converting to a byte array. The value must be a valid ${Charset}.
2287 If not specified, UTF-8 will be used.</td>
2288 </tr>
2289 <tr>
2290 <td>compact</td>
2291 <td>boolean</td>
2292 <td>If true, the appender does not use end-of-lines and indentation. Defaults to false.</td>
2293 </tr>
2294 <tr>
2295 <td>complete</td>
2296 <td>boolean</td>
2297 <td>If true, the appender includes the XML header and footer. Defaults to false.</td>
2298 </tr>
2299 <tr>
2300 <td>properties</td>
2301 <td>boolean</td>
2302 <td>If true, the appender includes the thread context map in the generated XML. Defaults to false.</td>
2303 </tr>
2304 <tr>
2305 <td>locationInfo</td>
2306 <td>boolean</td>
2307 <td>
2308 <p>If true, the appender includes the location information in the generated XML. Defaults to false.</p>
2309 <p>Generating <a href="#LocationInformation">location information</a>
2310 is an expensive operation and may impact performance. Use with caution.</p>
2311 </td>
2312 </tr>
2313 <tr>
2314 <td>includeStacktrace</td>
2315 <td>boolean</td>
2316 <td>If true, include full stacktrace of any logged #javadoc('java/lang', 'Throwable') (optional, default to true).</td>
2317 </tr>
2318 <tr>
2319 <td>stacktraceAsString</td>
2320 <td>boolean</td>
2321 <td>Whether to format the stacktrace as a string, and not a nested object (optional, defaults to false).</td>
2322 </tr>
2323 <tr>
2324 <td>includeNullDelimiter</td>
2325 <td>boolean</td>
2326 <td>Whether to include NULL byte as delimiter after each event (optional, default to false).</td>
2327 </tr>
2328 <caption align="top">XmlLayout Parameters</caption>
2329 </table>
2330 <p>
2331 To include any custom field in the output, use following syntax:
2332 </p>
2333 <pre class="prettyprint linenums">
2334 <XmlLayout>
2335 <KeyValuePair key="additionalField1" value="constant value"/>
2336 <KeyValuePair key="additionalField2" value="${dollar}${dollar}{ctx:key}"/>
2337 </XmlLayout>
2338 </pre>
2339 <p>
2340 Custom fields are always last, in the order they are declared. The values support <a href="lookups.html">lookups</a>.
2341 </p>
2342 <p>
2343 Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using XmlLayout.
2344 </p>
2345 </subsection>
2346 <a name="YamlLayout"/>
2347 <subsection name="YAML Layout">
2348 <p>
2349 Appends a series of YAML events as strings serialized as bytes.
2350 </p>
2351 <p>
2352 A YAML log event follows this pattern:
2353 </p>
2354 <pre class="prettyprint linenums">---
2355 instant:
2356 epochSecond: 1493121664
2357 nanoOfSecond: 118000000
2358 thread: "main"
2359 level: "INFO"
2360 loggerName: "HelloWorld"
2361 marker:
2362 name: "child"
2363 parents:
2364 - name: "parent"
2365 parents:
2366 - name: "grandparent"
2367 message: "Hello, world!"
2368 thrown:
2369 commonElementCount: 0
2370 message: "error message"
2371 name: "java.lang.RuntimeException"
2372 extendedStackTrace:
2373 - class: "logtest.Main"
2374 method: "main"
2375 file: "Main.java"
2376 line: 29
2377 exact: true
2378 location: "classes/"
2379 version: "?"
2380 contextStack:
2381 - "one"
2382 - "two"
2383 endOfBatch: false
2384 loggerFqcn: "org.apache.logging.log4j.spi.AbstractLogger"
2385 contextMap:
2386 bar: "BAR"
2387 foo: "FOO"
2388 threadId: 1
2389 threadPriority: 5
2390 source:
2391 class: "logtest.Main"
2392 method: "main"
2393 file: "Main.java"
2394 line: 29
2395 </pre>
2396 <table>
2397 <tr>
2398 <th>Parameter Name</th>
2399 <th>Type</th>
2400 <th>Description</th>
2401 </tr>
2402 <tr>
2403 <td>charset</td>
2404 <td>String</td>
2405 <td>The character set to use when converting to a byte array. The value must be a valid ${Charset}.
2406 If not specified, UTF-8 will be used.</td>
2407 </tr>
2408 <tr>
2409 <td>properties</td>
2410 <td>boolean</td>
2411 <td>If true, the appender includes the thread context map in the generated YAML. Defaults to false.</td>
2412 </tr>
2413 <tr>
2414 <td>locationInfo</td>
2415 <td>boolean</td>
2416 <td>
2417 <p>If true, the appender includes the location information in the generated YAML. Defaults to false.</p>
2418 <p>Generating <a href="#LocationInformation">location information</a>
2419 is an expensive operation and may impact performance. Use with caution.</p>
2420 </td>
2421 </tr>
2422 <tr>
2423 <td>includeStacktrace</td>
2424 <td>boolean</td>
2425 <td>If true, include full stacktrace of any logged #javadoc('java/lang', 'Throwable') (optional, default to true).</td>
2426 </tr>
2427 <tr>
2428 <td>stacktraceAsString</td>
2429 <td>boolean</td>
2430 <td>Whether to format the stacktrace as a string, and not a nested object (optional, defaults to false).</td>
2431 </tr>
2432 <tr>
2433 <td>includeNullDelimiter</td>
2434 <td>boolean</td>
2435 <td>Whether to include NULL byte as delimiter after each event (optional, default to false).</td>
2436 </tr>
2437 <caption align="top">YamlLayout Parameters</caption>
2438 </table>
2439 <p>
2440 To include any custom field in the output, use following syntax:
2441 </p>
2442 <pre class="prettyprint linenums">
2443 <YamlLayout>
2444 <KeyValuePair key="additionalField1" value="constant value"/>
2445 <KeyValuePair key="additionalField2" value="${dollar}${dollar}{ctx:key}"/>
2446 </YamlLayout>
2447 </pre>
2448 <p>
2449 Custom fields are always last, in the order they are declared. The values support <a href="lookups.html">lookups</a>.
2450 </p>
2451 <p>
2452 Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using YamlLayout.
2453 </p>
2454 </subsection>
2455 <a name="LocationInformation"/>
2456 <subsection name="Location Information">
2457 <p>
2458 If one of the layouts is
2459 configured with a location-related attribute like
2460 HTML <a href="#HtmlLocationInfo">locationInfo</a>,
2461 or one of the patterns
2462 <a href="#PatternClass">%C or %class</a>,
2463 <a href="#PatternFile">%F or %file</a>,
2464 <a href="#PatternLocation">%l or %location</a>,
2465 <a href="#PatternLine">%L or %line</a>,
2466 <a href="#PatternMethod">%M or %method</a>,
2467 Log4j will take a snapshot of the
2468 stack, and walk the stack trace to find the location information.
2469 </p>
2470 <p>
2471 This is an expensive operation: 1.3 - 5 times slower for
2472 synchronous loggers. Synchronous loggers wait as
2473 long as possible before they take this stack snapshot. If no
2474 location is required, the snapshot will never be taken.
2475 </p><p>
2476 However, asynchronous loggers need to make this decision before passing the
2477 log message to another thread; the location information will be lost after that point.
2478 The <a href="../performance.html#asyncLoggingWithLocation">performance impact</a>
2479 of taking a stack trace snapshot is even higher for asynchronous loggers:
2480 logging with location is 30-100 times slower than without location.
2481 For this reason, asynchronous loggers and asynchronous appenders do not include location information by default.
2482 </p><p>
2483 You can override the default behaviour in your logger
2484 or asynchronous appender configuration
2485 by specifying
2486 <tt>includeLocation="true"</tt>.
2487 </p>
2488 <p>
2489 </p>
2490 </subsection>
2491 </section>
2492 </body>
2493 </document>