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