Layouts
An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be
consuming the log event. In Log4j 1.x and Logback Layouts were expected to transform an event into a
String. In Log4j 2 Layouts return a byte array. This allows the result of the Layout to be useful in
many more types of Appenders. However, this means you need to configure most Layouts with a
Charset to
insure the byte array contains correct values.
HTMLLayout
The HTMLLayout generates an HTML page and adds each LogEvent to a row in a table.
HTML Layout Parameters
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 Charset.
If not specified, the default system Charset will be used. |
contentType |
String |
The value to assign to the Content-Type header. The default is "text/html". |
locationInfo |
boolean |
If true, the filename and line number will be included in the HTML output. The default value is
false. |
title |
String |
A String that will appear as the HTML title. |
PatternLayout
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 may be included in the conversion pattern.
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.
Pattern Layout Parameters
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 Charset.
If not specified, the default system Charset will be used.
|
pattern |
String |
|
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.
|
Patterns
The conversions that are provided with Log4j are:
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 byprecision specifier, which consists of a
decimal integer, or a pattern starting with a decimal integer.
If a precision specifier is given and it is an integer value, then only the corresponding number
of right most components of the logger name will be printed. If the precision contains
other non-integer characters then the name will be abbreviated based on the pattern. If the
precision integer is less than one the right-most token will still be printed in full.
By default the logger name is printed in full.
Conversion Pattern |
Logger Name |
Result |
%c{1} |
org.apache.commons.Foo |
Foo |
%c{2} |
org.apache.commons.Foo |
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 |
|
C{precision}
class{precision}
|
Outputs the fully qualified class name of the caller issuing the logging request.
This conversion specifier can be optionally followed byprecision specifier, that
follows the same rules as the logger name converter.
|
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
SimpleDateFormat.
The predefined formats are
ABSOLUTE,
COMPACT,
DATE,
ISO8601,
and
ISO8601_BASIC.
You can also use a set of braces containing a time zone id per
java.util.TimeZone.getTimeZone. If no date format specifier is given then ISO8601 format is assumed.
Pattern |
Example |
%d{ISO8601} |
2012-11-02 14:34:02,781 |
%d{ISO8601_BASIC} |
20121102 143402,781 |
%d{ABSOLUTE} |
14:34:02,781 |
%d{DATE} |
02 Nov 2012 14:34:02,781 |
%d{COMPACT} |
20121102143402781 |
%d{HH:mm:ss,SSS} |
14:34:02,781 |
%d{dd MMM yyyy HH:mm:ss,SSS} |
02 Nov 2012 14:34:02,781 |
%d{HH:mm:ss}{GMT+0} |
18:34:02,781 |
|
ex{["none"|"short"|"full"|depth]}
exception{["none"|"short"|"full"|depth]}
throwable{["none"|"short"|"full"|depth]}
|
Outputs the Throwable trace that has been bound to the LoggingEvent, by
default this will output the full trace as one would normally find by a call to
Throwable.printStackTrace().
The throwable conversion word can be followed by an option in the form
%throwable{short}
which will only output the first line of the Throwable or %throwable{n} where
the first n lines of the stacktrace will be printed. Specifying %throwable{none}
or %throwable{0} will suppress printing of the exception.
|
F
file
|
Outputs the file name where the logging request was issued.
|
highlight{pattern}{style}
|
Adds ANSI colors to the result of the enclosed pattern based on the current event's logging level.
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 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:
Style |
Description |
Default |
See above |
Logback |
Level |
ANSI color |
FATAL |
Blinking bright red |
ERROR |
Bright red |
WARN |
Red |
INFO |
Blue |
DEBUG |
Normal |
TRACE |
Normal |
|
|
K{key}
map{key}
MAP{key}
|
Outputs the entries in a
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}}
|
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.
|
L
line
|
Outputs the line number from where the logging request
was issued.
|
m
msg
message
|
Outputs the application supplied message associated with the logging event.
|
M
method
|
Outputs the method name where the logging request was issued.
|
marker
|
The name of the marker, if one is present. |
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.
|
p{level name mapping}
level{level name mapping}
|
Outputs the level of the logging event. A level name mapping map be provided 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. |
r
relative
|
Outputs the number of milliseconds elapsed since the JVM was started until the creation
of the logging event.
|
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.
|
rEx["none"|"short"|"full"|depth],[filters(packages)}
rException["none"|"short"|"full"|depth],[filters(packages)}
rThrowable["none"|"short"|"full"|depth],[filters(packages)}
|
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 stacktrace will be printed. The conversion word can also be
followed by "filters(packages)" where packages is a list of package names that should
be suppressed from stack traces. Specifying %rEx{none}
or %rEx{0} will suppress printing of the exception.
|
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. |
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.
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}
|
t
thread
|
Outputs the name of the thread that generated the logging event. |
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.
|
X{key}
mdc{key}
MDC{key}
|
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 the key 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 no additional sub-option
is specified, then the entire contents of the MDC key value pair set
is output using a format {{key1,val1},{key2,val2}}
See the
ThreadContext
class for more details.
|
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.
|
xEx{"none"|"short"|"full"|depth],[filters(packages)}
xException["none"|"short"|"full"|depth],[filters(packages)}
xThrowable["none"|"short"|"full"|depth],[filters(packages)}
|
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 stacktrace will be printed. The conversion word can also be
followed by "filters(packages)" where packages is a list of package names that should
be suppressed from stack traces. Specifying %xEx{none}
or %xEx{0} will suppress printing of the exception.
|
%
|
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.
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.
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.
|
ANSI Styling on Windows
ANSI escape sequences are supported natively on many platforms but are not by default on Windows. To
enable ANSI support simply add the Jansi jar to your
application and Log4j will automatically make use of it when writing to the console.
Example Patterns
Filtered Throwables
This example shows how to filter out classes from unimportant packages in stack traces.
<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.
<PatternLayout>
<pattern>%d %highlight{%p} %style{%C{1.} [%t] %m}{bold,green}%n</pattern>
</PatternLayout>
RFC5424Layout
As the name implies, the RFC5424Layout formats LogEvents in accordance with
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
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 Charset.
If not specified, the default system Charset will be used. |
enterpriseNumber |
integer |
The IANA enterprise number as described in
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. |
immediateFlush |
boolean |
When set to true, each write will be followed by a flush. This will guarantee the data is written
to disk but could impact performance. |
includeMDC |
boolean |
Indicates whether data from the ThreadContextMap will be included in the RFC 5424 Syslog record.
Defaults to true. |
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. |
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
The SerializedLayout simply serializes the LogEvent into a byte array. This is useful when
sending messages via JMS or via a Socket connection. The SerializedLayout accepts no parameters.
SyslogLayout
The SyslogLayout formats the LogEvent as BSD Syslog records matching the same format used by
Log4j 1.2.
SyslogLayout Parameters
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 Charset.
If not specified, the default system Charset will be used. |
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
The output of the XMLLayout consists of a series of log4j:event
elements as defined in the log4j.dtd. If configured to do so it will
output a complete well-formed XML file. The output is designed to be
included as an
external entity
in a separate file to form
a correct XML file.
For example, if abc is the name of the file where
the XMLLayout ouput goes, then a well-formed XML file would be:
<?xml version="1.0" ?>
<!DOCTYPE log4j:eventSet SYSTEM "log4j.dtd" [<!ENTITY data SYSTEM "abc">]>
<log4j:eventSet version="2.0" xmlns:log4j="http://logging.apache.org/log4j/">
</log4j:eventSet>
This approach enforces the independence of the XMLLayout and the appender where it is embedded.
The version attribute helps components to correctly intrepret output generated by XMLLayout.
The value of this attribute should be "2.0".
Appenders using this layout should have their encoding set to UTF-8 or UTF-16, otherwise events containing
non ASCII characters could result in corrupted log files.
|