Enhancements to `PatternLayout`

Introduction

The PatternLayout is by far the most widely used log4j layout. It formats logging events according to a conversion pattern specified by the user. Conversion patterns are composed of literal text and conversion specifiers. Literal text is output as is. Conversion specifiers consist of the % character followed by an optional format modifier and a mandatory conversion character. For example, %-5p [%t]: %m%n is a conversion pattern composed of a priority (a.k.a. level) conversion specifier followed by the literal text " ]", followed by a thread conversion specifier, followed by literal text "]: " followed by a message conversion specifier and a system dependent line separator. See PatternLayout documentation for more details.

Up until log4j 1.2, the set of conversion characters was limited to a single character, that is approximately to the characters in the latin alphabet. As time passed and the number of available characters shrunk, it became harder and harder to match the conversion character with its intended use. For example, the conversion specifiers '%x" and "%X" have little to do with the NDC and MDC. Another limitation of the existing PatternLayout was that it could only be extended by sub-classing. Thus, the set of recognized conversion specifiers was determined at compile time.

New functionality in version 1.3

In order to overcome the first limitation, the conversion specifiers are now composed of conversion words instead of a single conversion character. Here is a sample pattern that uses conversion words:

      %relative [%thread] %level %logger - %message%n

Note that the above pattern converter is strictly equivalent to:

     %r [%t] %p %c - %m%n

Mapping of conversion words to a PatternConverter

Each conversion word maps to a PatternConverter. Multiple conversion words can map to the same PatternConverter. Log4j ships with various pattern converters as listed below.

Conversion character or word	Associated `PatternConverter`	Description
c	`org.apache.log4j.pattern.LoggerPatternConverter`	Outputs the logger name of the LoggingEvent.
logger	`org.apache.log4j.pattern.LoggerPatternConverter`	An alias for "c".

F	`o.a.l.p.FileLocationPatternConverter`	Outputs the file name where the log request was issued.
file	`o.a.l.p.LoggerPatternConverter`	An alias for "F".

l	`o.a.l.p.LineLocationPatternConverter`	Outputs the line number where the log request was issued.
line	`o.a.l.p.LineLocationPatternConverter`	An alias for "l".

m	`o.a.l.p.MessagePatternConverter`	Outputs the message contained in the `LoggingEvent`.
message	`o.a.l.p.MessagePatternConverter`	An alias for "m".

n	`o.a.l.p.LineSeparatorPatternConverter`	Outputs the line separator as defined on the runtime platform.

M	`o.a.l.p.MethodLocationPatternConverter`	Outputs the method name where the log request was issued.
method	`o.a.l.p.MethodLocationPatternConverter`	An alias for "M".

p	`o.a.l.p.LevelPatternConverter`	Outputs the level (a.k.a. priority) of the `LoggingEvent`..
level	`o.a.l.p.LevelPatternConverter`	An alias for "p"

r	`o.a.l.p.RelativeTimePatternConverter`	Outputs the relative time in millisonds since program start.
relative	`o.a.l.p.RelativeTimePatternConverter`	Alias for "r".

t	`o.a.l.p.ThreadPatternConverter`	Outputs the name of the thread issuing the logging request.
thread	`o.a.l.p.ThreadPatternConverter`	An alias for "t"

x	`o.a.l.p.NDCPatternConverter`	Outputs the NDC associated with the thread issuing the logging request.
ndc	`o.a.l.p.NDCPatternConverter`	An alias for "x"

X	`o.a.l.p.MDCPatternConverter`	Outputs the MDC associated with the thread issuing the logging request. The conversion words should be followed by a key placed between braces. As in %x{clientNumber}.
mdc	`o.a.l.p.MDCPatternConverter`	An alias for "X"

Recognizing new conversion words

In order to make it easy for the user to extend the set of conversion specifiers without sub-classing, the PatternLayout is now capable of learning new conversion words dynamically. For example, the user can instruct a PatternLayout instance to recognize the word "counter" and associate it with the converter type "com.foo.CounterConverter". As mentioned previously, it is entirely possible to have the same PatternConverter class correspond to more than one conversion word. We have taken advantage of this feature to preserve full compatibility with version 1.2. PatternLayout in version 1.3 recognizes the the old conversion letter but also a new conversion word. For example, both "%X" and "%mdc" map to MDCPatternConverter.

The code snippet below illustrates the steps needed to add a new conversion word to a PatternLayout instance.

  PatternLayout pl = new PatternLayout();
  pl.addConversionRule("priority", "org.apache.log4j.pattern.LevelPatternConverter");
  pl.setConversionPattern("%relative %-5priority [%thread] - %m%n");
  // Only after caling the activateOptions method do the
  // conversion rule and conversion pattern have an effect.
  pl.activateOptions();

Defining your own pattern converters

A PatternLayout calls the format method of each of the pattern converters, according to their definition by the conversion pattern. The implementation of format method is the same across all pattern converters. However, this method delegates much of the formatting work to the convert method implemented in a specialized way by each pattern converter.

For examples of custom pattern converters please refer to the examples in the /examples/pattern/ directory.

In configuration files

The JoranConfigurator introduced in version 1.3 admits a new tag named "<conversionRule>" allowing a PatternConverter to learn a new conversion rule (i.e. an association of a conversion word and a converter class). This feature will be better documented in the near future.