Log4j Pattern Layout

From NovaOrdis Knowledge Base
Jump to navigation Jump to search

External

Internal

Overview

The pattern layout is defined by a conversion pattern string.

Conversion Pattern

The conversion pattern string specifies the various elements of a log event and the way they are intended to be displayed in a log file. The conversion pattern is closely related to the conversion pattern of the printf function in C. The conversion pattern is composed of:

There is no explicit separator between literal text and conversion specifiers. The pattern parser knows when it has reached the end of a conversion specifier when it reads a conversion character.

Literal Text

Literal text may include special characters (\t, \n \r \f). '\\' can be used to insert a backslash in the output.

Conversion Specifier

Each conversion specifier starts with a percent sign ('%') and it is followed by an optional format modifier and a mandatory conversion character:

%-5c

Format Modifier

A format modifier modifies how the data generated by the conversion specifier is displayed: field with, padding and justification. The format modifier is optional. It is placed between the percent sign and the conversion character.

The format modifier controls:

  • Left Justification -


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.

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.

Conversion Character

The conversion character specifies the type of data.

'c' Category (or Logger)

c{precision}

'd' Date

d

'm' Message

Application supplied message associated with this log event.

m

'n'

Platform dependent line separator.

n

'p' Level

The level of the logging event:

p

't' Thread Name

t

Throwable Handling

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 been 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.