# Chapter 5: Layouts

TCP implementations will follow a general principle of robustness: be conservative in what you do, be liberal in what you accept from others.

—JON POSTEL, RFC 793

## What is a layout?

While appenders are responsible for writing logging output to an appender dependent device, layouts are responsible for the format of the output. In case you were wondering, layouts have nothing to do with large estates in Florida. The `format()` method in the `Layout` interface takes an object that represents an event (of any type) and returns a String. A synopsis of the `Layout` interface is shown below.

public interface Layout<E> extends ContextAware, LifeCycle { String doLayout(E event); String getHeader(); String getFooter(); String getContentType(); }

This interface is rather simple and yet is sufficent for many formatting needs. The Texan developer from Texas, who you might know from Joseph Heller's Catch-22, might exclaim: it just takes five methods to implement a layout!!?

## Logback-classic

Logback-classic is wired to processes only events of type `ch.qos.logback.classic.spi.LoggingEvent`. This fact will apparent for the remaining of this section.

### Writing your own Layout

Let us implement a simple yet functional layout for the logback-classic module that prints the time elapsed since the start of the application, the level of the logging event, the caller thread between brackets, its logger name, a dash followed by the event message and a new line.

Sample output might look like:

10489 DEBUG [main] com.marsupial.Pouch - Hello world.

Here is a possible implementation, authored by the Texan developer:

Example 5.0: Sample implementation of a Layout (logback-examples/src/main/java/chapter5/MySampleLayout.java)

    package chapter5;

    import ch.qos.logback.classic.spi.LoggingEvent;
    import ch.qos.logback.core.LayoutBase;

    public class MySampleLayout extends LayoutBase<LoggingEvent> {

      public String doLayout(LoggingEvent event) {
        StringBuffer sbuf = new StringBuffer(128);
        sbuf.append(event.getTimeStamp() - LoggingEvent.getStartTime());
        sbuf.append(" ");
        sbuf.append(event.getLevel());
        sbuf.append(" [");
        sbuf.append(event.getThreadName());
        sbuf.append("] ");
        sbuf.append(event.getLoggerRemoteView().getName());
        sbuf.append(" - ");
        sbuf.append(event.getFormattedMessage());
        sbuf.append(LINE_SEP);
        return sbuf.toString();
      }
    }

Note that `MySampleLayout` extends `LayoutBase`. This class manages state shared by all `Layout` classes, such as whether the layout is started or stopped, header, footer and content type data. It allows the developer to concentrate on the formatting she expects from her `Layout`. Note that the `LayoutBase` class is generic. In its class declaration, `MySampleLayout` extends a typed `LayoutBase`, `LayoutBase<LoggingEvent>`, instead of generic one.

The `doLayout(LoggingEvent event)` method, i.e. the only method in `MySampleLayout`, begins by instantiating a `StringBuffer`. It proceeds by adding various fields of the event parameter. The Texan from Texas was careful to print the formatted form of the message. This is important when there are one or more parameters passed along with the logging request.

In the above listing of the `Layout` class, the `LINE_SEP` field is inherited from the `Layout` interface. It refers to the value returned by `System.getProperty("line.separator")` method, that is system dependent line separator character(s). After adding these system dependent character(s), the `doLayout()` method converts `sbuf` to `String` and returns the resulting value.

In the above example, the `doLayout` method ignores any eventual exceptions contained in the event. In a real world layout implementation, you would most probably want to print the contents of exceptions as well.

### Configuringyour custom layout

Custom layouts are configured as any other layout. Here is as example:

Example 5.0: Configuration of MySampleLayout (logback-examples/src/main/java/chapter5/sampleLayoutConfig.xml)

    <configuration>

      <appender name="STDOUT"
        class="ch.qos.logback.core.ConsoleAppender">
        <layout class="chapter5.MySampleLayout" />
      </appender>

      <root level="debug">
        <appender-ref ref="STDOUT" />
      </root>
    </configuration>

The sample application `chapter5.SampleLogging` configures logback with the configuration script supplied as parameter and then logs a debug message, followed by an error message.

To run this example issue the following command from within the logback-examples directory.

java chapter5.SampleLogging src/main/java/chapter5/sampleLayoutConfig.xml

This will produce:

    0 DEBUG [main] chapter5.SampleLogging - Everything's going well
    0 ERROR [main] chapter5.SampleLogging - maybe not quite...

That was simple enough. The skeptic Pyrrho of Elea, who insists that nothing is certain except perhaps uncertainty itself, which is by no means certain either, might ask: how about a layout with options? The reader shall find a slightly modified version of our custom layout in `MySampleLayout2.java`. She will discover that adding an option to a layout is as simple as declaring a setter method for the option.

The `MySampleLayout2` class contains two attributes. The first one is a prefix that can be added to the output. The second attribute is used to choose wether to display the name of the thread from which the logging request was sent.

Here is the implementation of this class:

package chapter5; import ch.qos.logback.classic.spi.LoggingEvent; import ch.qos.logback.core.LayoutBase; public class MySampleLayout2 extends LayoutBase<LoggingEvent> { String prefix = null; boolean printThreadName = true; public void setPrefix(String prefix) { this.prefix = prefix; } public void setPrintThreadName(boolean printThreadName) { this.printThreadName = printThreadName; } public String doLayout(LoggingEvent event) { StringBuffer sbuf = new StringBuffer(128); if (prefix != null) { sbuf.append(prefix + ": "); } sbuf.append(event.getTimeStamp() - LoggingEvent.getStartTime()); sbuf.append(" "); sbuf.append(event.getLevel()); if (printThreadName) { sbuf.append(" ["); sbuf.append(event.getThreadName()); sbuf.append("] "); } else { sbuf.append(" "); } sbuf.append(event.getLoggerRemoteView().getName()); sbuf.append(" - "); sbuf.append(event.getFormattedMessage()); sbuf.append(LINE_SEP); return sbuf.toString(); } }

The addition of the corresponding setter method is all that is needed to enable the configuration of an option. Note that the `PrintThreadName` option is boolean and not `String`. Configuration of logback components was covered in detail in "Chapter 3: Logback configuration". Here is the configuration file tailor-made for use with `MySampleLayout2`.

<configuration> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="chapter5.MySampleLayout2"> <prefix>MyPrefix</prefix> <printThreadName>false</printThreadName> </layout> </appender> <root level="debug"> <appender-ref ref="STDOUT" /> </root> </configuration>

### PatternLayout

Logback classic ships with a flexible layout called `PatternLayout`. As all layouts, `PatternLayout` takes a logging event and returns a `String`. However, this `String` can be customized at will by tweaking the conversion pattern of `PatternLayout`.

The conversion pattern of `PatternLayout` is closely related to the conversion pattern of the `printf()` function in the C programming language. A conversion pattern is composed of literal text and format control expressions called conversion specifiers. You are free to insert any literal text within the conversion pattern. Each conversion specifier starts with a percent sign '%' and is followed by optional format modifiers, a conversion word and optional parameters between braces. The conversion word controls the type of data to use, e.g. logger name, level, date, thread name. The format modifiers control such things as field width, padding, and left or right justification. The following is a simple example.

Example 5.1: Sample usage of a PatternLayout (logback-examples/src/main/java/chapter5/PatternSample.java)

    package chapter5;

    import org.slf4j.LoggerFactory;

    import ch.qos.logback.classic.Logger;
    import ch.qos.logback.classic.PatternLayout;
    import ch.qos.logback.core.ConsoleAppender;

    public class PatternSample {

      static public void main(String[] args) throws Exception {
        Logger rootLogger = (Logger)LoggerFactory.getLogger("root");

        PatternLayout layout = new PatternLayout();
        layout.setPattern("%-5level [%thread]: %message%n");
        layout.start();

        ConsoleAppender<LoggingEvent> appender = new ConsoleAppender<LoggingEvent>();
        appender.setContext(rootLogger.getLoggerContext());
        appender.setLayout(layout); appender.start();

        rootLogger.addAppender(appender);

        rootLogger.debug("Message 1");
        rootLogger.warn("Message 2");
      }
    }

The conversion pattern is set to be "%-5level [%thread]: %message%n". Running PatternSample will yield the following output on the console.

DEBUG [main]: Message 1 WARN [main]: Message 2

Note that in the conversion pattern "%-5level [%thread]: %message%n" there is no explicit separator between literal text and conversion specifiers. When parsing a conversion pattern, `PatternLayout` is capable of differentiating between literal text (space characters, the brackets, colon character) and conversion specifiers. In the example above, the conversion specifier %-5level means the level of the logging event should be left justified to a width of five characters. Format specifiers will be explained in a short moment.

In PatternLayout, parenthesis can be used to group conversion patterns. It follows that the '(' and ')' carry special meaning and need to be escaped to be used as literals. Parentheses can be escaped by preceding the the opening and closing parenthesis by backslash, but since backslash itself carries special meaning in Java, we need two backslashes, as in "\\(" and "\\)". Note that strictly speaking, only the closing parenthesis needs to be escaped to be used as a literal.

As mentionned previously, certain conversion specifiers can include optional parameters which are passed between braces following the conversion word. A sample conversion specifier with options could be `%logger{10}`. Here "logger" is the conversion word, and 10 is the option.

The recognized conversions words along with their options are described in the table below. When multiple conversion words are listed on the left column, they should be considered as aliases.

Conversion Word | Effect
--- | ---
c{length} lo{length} logger{length} | Used to output the name of the logger at the origin of the logging event. This conversion word can take an integer as its first and only option. The converter's abbreviation algorithm will shorten the logger name, usually without significant loss of meaning. Setting the value of this option to zero will cause the conversoin specifier to return the string right to the rightmost dot character. The next table provides examples of the abbreviation algorithm in action.
Conversion specifier | Logger name | Result
--- | --- | ---
%logger | mainPackage.sub.sample.Bar | mainPackage.sub.sample.Bar
%logger{0} | mainPackage.sub.sample.Bar | Bar
%logger{10} | mainPackage.sub.sample.Bar | m.s.s.Bar
%logger{15} | mainPackage.sub.sample.Bar | m.s.sample.Bar
%logger{16} | mainPackage.sub.sample.Bar | m.sub.sample.Bar
%logger{26} | mainPackage.sub.sample.Bar | mainPackage.sub.sample.Bar
C{length} class{length} | Used to output the fully qualified class name of the caller issuing the logging request. Just like the %logger conversion word above, this word can take an interger as it's first option and use its abbreviation algorithm to shorten the class name. Zero carries special meaning and w will cause the simple class name to be output without its package name prefix. By default the class name is output in full. Generating the caller class information is not particularly fast. Thus, it's use should be avoided unless execution speed is not an issue.
contextName cn | Outputs the name of the logger context to which the logger at the origin of the logging event is attached to.
d{pattern} date{pattern} | Used to output the date of the logging event. The date conversion word may be followed by an option enclosed between braces. The option admits the same syntax as the time pattern string of the `java.text.SimpleDateFormat`. A shortcut to the ISO8601 format is available by specifying the String "ISO8601" in the braces. If no option is set, the converter uses "ISO8601" as the default value. Here are some sample option values. They assume that the actual date is Friday 20th of October, 2006 and that the author finished his meal a short while ago.
Conversion Pattern | Result
--- | ---
%date | 2006-10-20 14:46:49,812
%date{ISO8601} | 2006-10-20 14:46:49,812
%date{HH:mm:ss.SSS} | 14:46:49.812
%date{dd MMM yyyy ;HH:mm:ss.SSS} | 20 oct. 2006;14:46:49.812
F / file | Used to output the file name of the Java source file where the logging request was issued. Generating the file information is not particularly fast. Thus, it's use should be avoided unless execution speed is not an issue.
caller{depth} caller{depth, evaluator-1, ... evaluator-n} | Used to output 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 caller's source the file name and line number between parentheses. A integer can be added to the caller conversion specifier's options to configure the depth of the information to be displayed. For example, %caller{2} would display the following excerpt:
    0    [main] DEBUG - logging statement
    Caller+0   at mainPackage.sub.sample.Bar.sampleMethodName(Bar.java:22)
    Caller+1   at mainPackage.sub.sample.Bar.createLoggingRequest(Bar.java:17)
And %caller{3} would display this other excerpt: 16 [main] DEBUG - logging statement Caller+0 at mainPackage.sub.sample.Bar.sampleMethodName(Bar.java:22) Caller+1 at mainPackage.sub.sample.Bar.createLoggingRequest(Bar.java:17) Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38) This conversion word can also use evaluators to test logging events against a given criteria before creating the output. For example, using %caller{3, CALLER_DISPLAY_EVAL} will display three lines of stacktrace, only if the evaluator called CALLER_DISPLAY_EVAL returns a positive answer. Evaluators are described further down this document.
L / line | Used to output the line number from where the logging request was issued. Generating the line number information is not particularly fast. Thus, it's use should be avoided unless execution speed is not an issue.
m / msg / message | Used to output the application supplied message associated with the logging event.
M / method | Used to output the method name where the logging request was issued. Generating the method name is not particularly fast. Thus, it's use should be avoided unless execution speed is not an issue.
n | Outputs the platform dependent line separator character or characters. This conversion word 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 / le / level | Used to output the level of the logging event.
r / relative | Used to output the number of milliseconds elapsed since the start of the application until the creation of the logging event.
t / thread | Used to output the name of the thread that generated the logging event.
X{key} mdc{key} | Used to output the MDC (mapped diagnostic context) associated with the thread that generated the logging event. If mdc conversion word is followed by a key between braces, as in %mdc{clientNumber}, then the value in the MDC corresponding to the key will be output. If no option is given, then the entire content of the MDC will be output in the format "key1=val1, key2=val2". See Chapter 7 for more details on the MDC.
ex{length} exception{length} throwable{length} ex{length, evaluator-1, ..., evaluator-n} exception{length, evaluator-1, ..., evaluator-n} throwable{length, evaluator-1, ..., evaluator-n} | Used to output the stack trace of the exception associated with the logging event, if any. By default the full stack trace will be output. If you do not specify the %ex conversion word (or one of its aliases) in the conversion pattern, `PatternLayout` will automatically add it as the last conversion word, on account of the importance of stack trace information. The $nopex conversion word can be substituted for %ex, in case you do not wish stack trace information to be displayed. See also %nopex conversion word. The throwable conversion word can followed by one of the following options: short: prints the first line of the stack trace full: prints the full stack trace Any integer: prints the given number of lines of the stack trace Here are some examples:
Conversion Pattern | Result
--- | ---
%ex |
    mainPackage.foo.bar.TestException: Houston we have a problem
      at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22)
      at mainPackage.foo.bar.TestThrower.readyToLaunch(TestThrower.java:17)
      at mainPackage.ExceptionLauncher.main(ExceptionLauncher.java:38)
%ex{short} |
    mainPackage.foo.bar.TestException: Houston we have a problem
      at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22)
%ex{full} |
    mainPackage.foo.bar.TestException: Houston we have a problem
      at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22)
      at mainPackage.foo.bar.TestThrower.readyToLaunch(TestThrower.java:17)
      at mainPackage.ExceptionLauncher.main(ExceptionLauncher.java:38)
%ex{2} |
    mainPackage.foo.bar.TestException: Houston we have a problem
      at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22)
      at mainPackage.foo.bar.TestThrower.readyToLaunch(TestThrower.java:17)
This conversion word can also use evaluators to test logging events against a given criteria before creating the output. For example, using %ex{full, EX_DISPLAY_EVAL} will display the full stacktrace of the exception, only if the evaluator called EX_DISPLAY_EVAL returns a negative answer. Evaluators are described further down in this document.
xEx{length} xException{length} xThrowable{length} xEx{length, evaluator-1, ..., evaluator-n} xException{length, evaluator-1, ..., evaluator-n} xThrowable{length, evaluator-1, ..., evaluator-n} | Same as the %exception conversion keyword with the addition of class packaging information. At the end of each stack frame of the exception, a string consisting of the jar file containing the relevant class followed by the "Implementation-Version" as found in that jar's manifest will be added. This innovative technique was suggested by James Strachan. If the information is uncertain, then the class packaging data will be preceded by a tilde, i.e. the '~' character. Here is an example: java.lang.NullPointerException at com.xyz.Wombat(Wombat.java:57) ~[wombat-1.3.jar:1.3] at com.xyz.Wombat(Wombat.java:76) ~[wombat-1.3.jar:1.3] at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:1.5.0_06] at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[na:1.5.0_06] at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[na:1.5.0_06] at java.lang.reflect.Method.invoke(Method.java:585) ~[na:1.5.0_06] at org.junit.internal.runners.TestMethod.invoke(TestMethod.java:59) [junit-4.4.jar:na] at org.junit.internal.runners.MethodRoadie.runTestMethod(MethodRoadie.java:98) [junit-4.4.jar:na] ...etc Logback goes to great lengths to ensure that the class packaging information it displays is correct, even in arbirarily complex class loader hierarchies. However, when it is not able to guarantee the absolute correctness of the information, then it will prefix the data with a tilde, i.e. the '~' character. Thus, it is theoretically possible for the printed class packaging information to differ from the real class packaging information. So, in the above example, given that packaging data for the Wombat class is preceded by a tilde, it possible that the correct packaging data is in reality [wombat.jar:1.7].
nopex nopexception | Altough it pretends to handle stack trace data, this conversion word does not output any data, thus, effectively ignoring exceptions. The %nopex conversion word allows the user to override PatternLayout's internal safety mechanism which silently adds %ex conversion keyword, even it was not specified in the conversion pattern.
marker | Used to output the marker associated with the logger request. In case the marker contains children markers, the converter displays the parent as well as childrens' names according to the format shown below. parentName [ child1, child2 ]

Given that in the context of conversion patterns the percent sign carries special meaning, in order to include it as a literal, it needs to be escaped with a backslash, e.g. "%d %p \% %m%n".

## Format modifiers

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 as well as justification.

The optional format modifier is placed between the percent sign and the conversion character or word.

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 contains 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. For example, if 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 logger conversion specifier.

Format modifier | Left justify | Minimum width | Maximum width | Comment
--- | --- | --- | --- | ---
%20logger | false | 20 | none | Left pad with spaces if the logger name is less than 20 characters long.
%-20logger | true | 20 | none | Right pad with spaces if the logger name is less than 20 characters long.
%.30logger | NA | none | 30 | Truncate from the beginning if the logger name is longer than 30 characters.
%20.30logger | false | 20 | 30 | Left pad with spaces if the logger name is shorter than 20 characters. However, if logger name is longer than 30 characters, then truncate from the beginning.
%-20.30logger | true | 20 | 30 | Right pad with spaces if the logger name is shorter than 20 characters. However, if logger name is longer than 30 characters, then truncate from the beginning.
%.-30logger | NA | none | 30 | Truncate from the end if the logger name is longer than 30 characters.

The table below list examples for format modifier truncation. Please note that the brackets, i.e the pair of "[]" characters, are not part of the output. They are used to delimit the width of output.

Format modifier | Logger name | Result
--- | --- | ---
[%20.20logger] | main.Name |
    [           main.Name]
[%-20.20logger] | main.Name |
    [main.Name           ]
[%10.10logger] | main.foo.foo.bar.Name |
    [o.bar.Name]
[%10.-10logger] | main.foo.foo.bar.Name |
    [main.foo.f]

### Parentheses are special

In logback, parentheses within the pattern string are treated as grouping tokens. Thus, it is possible to group a sub-pattern and apply formatting directives on that sub-pattern.

For example, the pattern

%-30(%d{HH:mm:ss.SSS} [%thread]) %-5level %logger{32} - %msg%n

will group the output generated by the sub-pattern "%d{HH:mm:ss.SSS} [%thread]" so that it is right-padded if less than 30 characters.

If without the grouping the output was

13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Classload hashcode is 13995234 13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Initializing for ServletContext 13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Trying platform Mbean server 13:09:30 [pool-1-thread-1] INFO ch.qos.logback.demo.LoggingTask - Howdydy-diddly-ho - 0 13:09:38 [btpool0-7] INFO c.q.l.demo.lottery.LotteryAction - Number: 50 was tried. 13:09:40 [btpool0-7] INFO c.q.l.d.prime.NumberCruncherImpl - Beginning to factor. 13:09:40 [btpool0-7] DEBUG c.q.l.d.prime.NumberCruncherImpl - Trying 2 as a factor. 13:09:40 [btpool0-7] INFO c.q.l.d.prime.NumberCruncherImpl - Found factor 2

with the "%-30()" grouping it would be

13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Classload hashcode is 13995234 13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Initializing for ServletContext 13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Trying platform Mbean server 13:09:30 [pool-1-thread-1] INFO ch.qos.logback.demo.LoggingTask - Howdydy-diddly-ho - 0 13:09:38 [btpool0-7] INFO c.q.l.demo.lottery.LotteryAction - Number: 50 was tried. 13:09:40 [btpool0-7] INFO c.q.l.d.prime.NumberCruncherImpl - Beginning to factor. 13:09:40 [btpool0-7] DEBUG c.q.l.d.prime.NumberCruncherImpl - Trying 2 as a factor. 13:09:40 [btpool0-7] INFO c.q.l.d.prime.NumberCruncherImpl - Found factor 2

The latter form is more comfortable to read, especially for long log files.

If you need to treat the parenthesis character as a literal, they needs to be escaped by preceding each parenthesis with a backslash. As in, \(%d{HH:mm:ss.SSS} [%thread]\). Strictly speaking, only the closing parentesis needs to be escaped. Thus, "%d [%thread]\)" is equivalent to "\(%d [%thread]\)".

### Options

A conversion specifier can be followed by options. The are always declared between braces. We have already seen some of the possibilities offered by options, for instance in conjunction with the MDC conversion specifier, as in: %mdc{someKey}.

A conversion specifier might have more than one option. For example, a conversion specifier that makes use of evaluators, which will be covered soon, may add evaluator names to the option list, as shown below:

      <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <layout class="ch.qos.logback.classic.PatternLayout">
          <param name="Pattern" value="%-4relative [%thread] %-5level - %msg%n \
            %caller{2, DISP_CALLER_EVAL, OTHER_EVAL_NAME, THIRD_EVAL_NAME}" />
        </layout>
      </appender>

### Evaluators

As mentioned above, option lists come in handy when a conversion specifier is required to behave dynamically based on one or more `EventEvaluator` objects. `EventEvaluator` objects have the responsibility to determine whether a given logging event matches the criteria of the evaluator.

Let us review an example with `EventEvaluator` objects. The following configuration file outputs the logging events to the console, displaying date, thread, level, message and caller data. Given that extracting the caller data of a logging event is on expensive side, we will do so only when the logging request originates from a specific logger, and whose message contains a certain string. Thus, we make sure that only specific logging requests will have their caller information generated and displayed. In other cases, where the caller data is superfluous, we will not penalize application performance.

Example 5.2: Sample usage of EventEvaluators (logback-examples/src/main/java/chapter5/callerEvaluatorConfig.xml)

<configuration> <evaluator name="DISP_CALLER_EVAL"> <Expression>logger.getName().contains("chapter5") &amp;&amp; \ message.contains("who calls thee")</Expression> </evaluator> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> <Pattern>%-4relative [%thread] %-5level - %msg%n%caller{2, DISP_CALLER_EVAL} </Pattern> </layout> </appender> <root level="debug"> <appender-ref ref="STDOUT" /> </root> </configuration>

Due to XML encoding rules, the & character cannot be written as is, and needs to be escaped as &amp;.

The above configuration file is designed to be accompanied by the following custom-tailored code.

Example 5.2: Sample usage of EventEvaluators (logback-examples/src/main/java/chapter5/CallerEvaluatorExample.java)

package chapter5; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import ch.qos.logback.classic.LoggerContext; import ch.qos.logback.classic.joran.JoranConfigurator; import ch.qos.logback.core.joran.spi.JoranException; import ch.qos.logback.core.util.StatusPrinter; public class CallerEvaluatorExample { public static void main(String[] args) { Logger logger = LoggerFactory.getLogger(CallerEvaluatorExample.class); LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); try { JoranConfigurator configurator = new JoranConfigurator(); configurator.setContext(lc); configurator.doConfigure(args[0]); } catch (JoranException je) { StatusPrinter.print(lc); } for (int i = 0; i < 5; i++) { if (i == 3) { logger.debug("who calls thee?"); } else { logger.debug("I know me " + i); } } } }

The CallerEvaluatorExample application does nothing particularly fancy. Five logging requests are issued, the third one being different from the others.

When a logging request is issued, the corresponding logging event goes through the evaluation process. The third request matches the evaluation criteria, causing its caller data to be displayed.

Here is the output of the `CallerEvaluatorExample` class.

    0    [main] DEBUG - I know me 0
    0    [main] DEBUG - I know me 1
    0    [main] DEBUG - I know me 2
    0    [main] DEBUG - who calls thee?
    Caller+0   at chapter5.CallerEvaluatorExample.main(CallerEvaluatorExample.java:28)
    0    [main] DEBUG - I know me 4

One can change the expression to correspond a real world scenario. For instance, one could combine the logger name and request level. Thus, logging requests of level WARN and up, originating from a sensitive part of an application, e.g. a financial transaction module, would have their caller data displayed.

Important: With the caller conversion specifier, the data is displayed when the expression evaluates to true.

Let us consider at a different situation. When exceptions are included in a logging request, their stack trace is usually displayed. However, in some cases, one might want to supress the stack trace of some specific exception.

The java code shown below creates five log requests, each with an exception. However, it so happends that we do not wish the stack trace of the third request to be output.

Example 5.2: Sample usage of EventEvaluators (logback-examples/src/main/java/chapter5/ExceptionEvaluatorExample.java)

    package chapter5;

    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;

    import ch.qos.logback.classic.LoggerContext;
    import ch.qos.logback.classic.joran.JoranConfigurator;
    import ch.qos.logback.core.joran.spi.JoranException;
    import ch.qos.logback.core.util.StatusPrinter;

    public class ExceptionEvaluatorExample {

      public static void main(String[] args) {
        Logger logger = LoggerFactory.getLogger(ExceptionEvaluatorExample.class);
        LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();

        try {
          JoranConfigurator configurator = new JoranConfigurator();
          configurator.setContext(lc);
          configurator.doConfigure(args[0]);
        } catch (JoranException je) {
          StatusPrinter.print(lc);
        }
        for (int i = 0; i < 5; i++) {
          if (i == 3) {
            logger.debug("logging statement " + i, new TestException(
                "do not display this"));
          } else {
            logger.debug("logging statement " + i, new Exception("display"));
          }
        }
      }
    }

The following configuration will supress the stack trace of the third logging request.

Example 5.3: Sample usage of EventEvaluators (logback-examples/src/main/java/chapter5/exceptionEvaluatorConfig.xml)

    <configuration>

      <evaluator name="DISPLAY_EX_EVAL">
        <Expression>throwable != null &amp;&amp; throwable instanceof  \
          chapter5.TestException</Expression>
      </evaluator>

      <appender name="STDOUT"
        class="ch.qos.logback.core.ConsoleAppender">
        <layout class="ch.qos.logback.classic.PatternLayout">
          <Pattern>%-4relative [%thread] %-5level - %msg%n%ex{full, DISPLAY_EX_EVAL}
          </Pattern>
        </layout>
      </appender>

      <root level="debug">
        <appender-ref ref="STDOUT" />
      </root>
    </configuration>

With this configuration, each time an instance of the chapter5.TestException is included within a logging request, the stack trace will be suppressed.

Important: With the %ex conversion specifier, the stack trace is displayed when the expression evaluates to false.

## Creating a custom conversion specifier

Up to this point we have presented the built-inconversion specifiers of `PatternLayout`. But it is also possible to use a conversion specifier of your own making.

Building a custom conversion specifier consists of two steps.

First, you must sub-class the `Converter` class. `Converter` objects are responsible for extracting information out of `LoggingEvent` objects and returning it as String. For example, the `LoggerConverter`, the converter underlying the %logger conversion word, extracts the name of the logger from the `LoggingEvent` and returns it as a String. It might abbreviate the logger name in the process.

Let us say that our customized `Converter` colors the level of the logging event, according to ANSI terminal conventions. Here is a possible implementation:

Example 5.4: Sample Converter Example (src/main/java/chapter5/MySampleConverter.java)

    package chapter5;

    import ch.qos.logback.classic.Level;
    import ch.qos.logback.classic.pattern.ClassicConverter;
    import ch.qos.logback.classic.spi.LoggingEvent;

    public class MySampleConverter extends ClassicConverter {

      private static final String END_COLOR = "\u001b[m";

      private static final String ERROR_COLOR = "\u001b[0;31m";
      private static final String WARN_COLOR = "\u001b[0;33m";

      @Override
      public String convert(LoggingEvent event) {
        StringBuffer sbuf = new StringBuffer();
        sbuf.append(getColor(event.getLevel()));
        sbuf.append(event.getLevel());
        sbuf.append(END_COLOR);
        return sbuf.toString();
      }

      /**
       * Returns the appropriate characters to change the color for the specified
       * logging level.
       */
      private String getColor(Level level) {
        switch (level.toInt()) {
        case Level.ERROR_INT:
          return ERROR_COLOR;
        case Level.WARN_INT:
          return WARN_COLOR;
        default:
          return "";
        }
      }
    }

java chapter5.SampleLogging src/main/java/chapter5/mySampleConverterConfig.xml

This implementation is relatively straightforward. The `MySampleConverter` class extends `ClassicConverter`, and implements the `convert` method where it returns a level string decorated with ANSI coloring codes.

In the second step, we must let logback know about the new `Converter`. For this purpose, we need to declare the new conversion word in the configuration file, as shown below:

Example 5.4: Sample Converter Example (src/main/java/chapter5/mySampleConverterConfig.xml)

    <configuration>

      <conversionRule conversionWord="sample" converterClass="chapter5.MySampleConverter" />

      <appender name="STDOUT"
        class="ch.qos.logback.core.ConsoleAppender">
        <layout class="ch.qos.logback.classic.PatternLayout">
          <Pattern>%-4relative [%thread] %sample - %msg%n</Pattern>
        </layout>
      </appender>

      <root level="debug">
        <appender-ref ref="STDOUT" />
      </root>
    </configuration>

In this configuration file, once the new conversion word has been declared, we can refert to it within a `PatternLayout` pattern, as if the custom conversion word had always been here.

Given that ANSI terminal codes do not work on Windows, you can view the results on non-Windows platforms such as Linux or Mac. The following command:

java chapter5.SampleLogging src/main/java/chapter5/mySampleConverterConfig.xml

should yield:

0 [main] DEBUG - Everything's going well 3 [main] ERROR - maybe not quite...

Please note that the string "ERROR" is highlighted in red, which was somewhat the point of the exercise.

The intersted reader might want to take a look at other `Converter` implementations such as `MDCConverter` to learn about more complex behaviours, such as option handling.

### HTMLLayout

`HTMLLayout` (as included in logback-classic) generates logs in HTML format. `HTMLLayout` outputs logging events in an HTML table where each row of the table corresponds to a logging event.

Here is a sample output produced by `HTMLLayout` using its default CSS stylesheet:

The content of table columns are specified with the help of a conversion pattern. See `PatternLayout` for documentation on conversion patterns. As such, you have full control over the contents and format of the table. You can select and display any combination of converters `PatternLayout` knows about.

One notable exception about the use of `PatternLayout` with `HTMLLayout` is that conversion specifiers should not be separated by space characters or more generally by literal text. Each specifier found in the pattern will result in a separate column. Likewise a separate column will be generated for each block of literal text found in the pattern potentially wasting valuable real estate on your screen.

Here is simple but functional configuration file illustrating the use of `HTMLLayout`.

<configuration debug="true"> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <layout class="ch.qos.logback.classic.html.HTMLLayout"> <pattern>%relative%thread%mdc%level%logger%msg</pattern> </layout> <File>/test.html</File> </appender> <root level="debug"> <appender-ref ref="FILE" /> </root> </configuration>

Launching the `TrivialMain` application listed below will create the file test.html on your local drive.

import org.slf4j.Logger; import org.slf4j.LoggerFactory; public class TrivialMain { public static void main(String[] args) throws InterruptedException { Logger logger = LoggerFactory.getLogger(TrivialMain.class); for(int i = 0; i < 6; i ++) { if(i % 5 == 0) { logger.info("an info message "+i); } else { logger.debug("hello world number" +i); } } logger.error("Finish off with fireworks", new Exception("Just testing")); } }

The contents of test.html should be similar to:

### Stack traces

If you use the %em conversion word to display stack traces, a table column will be created to display stack traces. In most cases the column will be empty, wasting screen real-estate. Moreover, printing a stack trace on a separate column does not yield very readable results. Fortunately, the %ex conversion word is not the only way to display stack traces.

A better solution is available through implementations of `IThrowableRenderer` interface. Such an implementation can be assigned to `HTMLLayout` to manage the display data related to exceptions. By default, a `DefaultThrowableRenderer` is assigned to each `HTMLLayout` instance. It writes exceptions on a new table row, along with its stacktrace, in an easily readable manner, as shown on the figure above.

If for some reason, you still wish to use the %ex pattern, then you can specify `NOPThrowableRenderer` in the configuration file in order to disable displaying a separate row for the stack trace. We don't have the faintest idea why you would want to do that, but if you wished, you could.

### CSS

The presentation of the HTML created by `HTMLLayout` is controlled through a Cascading Style Sheet (CSS). In the absence of specific instructions, `HTMLLayout` will default to its internal CSS. However, your can instruct `HTMLLayout` to use an external CSS file. For this purpose a `cssBuilder` element can be nested within a `<layout>` element, as shown below.

    <layout>
      ...
      <cssBuilder class="ch.qos.logback.core.html.UrlCssBuilder">
        <url>path_to_StyleFile.css</url>
      </cssBuilder>
      ...
    </layout>

The `HTMLLayout` is often used in conjunction with `SMTPAppender`, in order to send an email pleasantly formatted in HTML. Here is a typical configuration:

    <configuration>
      <appender name="SMTP" class="ch.qos.logback.classic.net.SMTPAppender">
        <layout class="ch.qos.logback.classic.html.HTMLLayout">
          <pattern>%relative%thread%mdc%level%class%msg</pattern>
        </layout>
        <From>sender.email@domain.net</From>
        <SMTPHost>mail.domain.net</SMTPHost>
        <Subject>LastEvent: %class - %msg </Subject>
        <To>destination.email@domain.net</To>
      </appender>

      <root level="debug">
        <appender-ref ref="SMTP" />
      </root>
    </configuration>

`HTMLLayout` can also be used with any `FileAppender`, including a a rolling file appender, as shown in the sample configuration below.

<configuration> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <ActiveFileName>lastLogEntries.html</ActiveFileName> <FileNamePattern>logEntries.%d{yyyy-MM-dd}.log</FileNamePattern> </rollingPolicy> <layout class="ch.qos.logback.classic.html.HTMLLayout"> <cssBuilder class="ch.qos.logback.core.html.UrlCssBuilder"> <url>address_of_a_custom_stylesheet.css</url> </cssBuilder> <Pattern>%relative%thread%mdc%level%logger%msg</Pattern> <Title>Logging Events</Title> </layout> </appender> <root level="debug"> <appender-ref ref="FILE" /> </root> </configuration>

### Log4j XMLLayout

XMLLayout (part of logback-classic) generates output in a log4j.dtd compliant format. It can be used to inter-operate with tools such as Chainsaw and Vigilog capable of processing files generated by log4j's XMLLayout.

As the original XMLLayout in log4j version 1.2.15, XMLLayout in logback-classic admits two boolean properties, LocationInfo and Properties. Setting LocationInfo to true enables the inclusion of location info (caller data) in the each event. Setting Properties to true enables the inclusion of MDC information. Both options are set to false by default.

Here is a sample configuration

<configuration> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <File>test.xml</File> <layout class="ch.qos.logback.classic.log4j.XMLLayout"> <LocationInfo>true</LocationInfo> </layout> </appender> <root level="debug"> <appender-ref ref="FILE" /> </root> </configuration>

## Logback access

Most logback-access layouts are mere adaptations of logback-classic layouts. Logback-classic and logback-access modules address different needs, but in general offer comparable functionality.

### Writing your own Layout

Writing a custom `Layout` for logback access is nearly identical as its sibling`Layout` in logback-classic.

### PatternLayout

`PatternLayout` in logback-access can be configured much in the same way as its classic counterpart. However it features additional conversion specifiers suited for logging particular bits of information availalbe only in HTTP servlet requests and HTTP servlet responses.

Below is a list of conversion specifiers for `PatternLayout` in logback-access.

Conversion Word | Effect
--- | ---
a / remoteIP | Remote IP address.
A / localIP | Local IP address.
b / B / byteSent | Response's content length.
h / clientHost | Remote host.
H / protocol | Request protocol.
l | Remote log name. In logback-access, this converter always returns the value "-".
reqParameter{paramName} | Parameter of the response. This conversion word takes the first option in braces and looks for the corresponding parameter in the request. %reqParameter{input_data} displays the corresponding parameter.
i{header} / header{header} | Request header. This conversion word takes the first option in braces and looks for the corresponding header in the request. %header{Referer} displays the referer of the request. If no option is specified, it displays every available header.
m / requestMethod | Request method.
r / requestURL | URL requested.
s / statusCode | Status code of the request.
t / date | Used to output the date of the logging event. The date conversion specifier may be followed by a set of braces containing a date and time pattern strings used by `java.text.SimpleDateFormat`. ABSOLUTE, DATE or ISO8601 are also valid values. For example, %d{HH:mm:ss,SSS}, %d{dd MMM yyyy ;HH:mm:ss,SSS} or %d{DATE}. If no date format specifier is given then ISO8601 format is assumed.
u / user | Remote user.
U / requestURI | Requested URI.
v / server | Server name.
localPort | Local port.
reqAttribute{attributeName} | Attribute of the request. This conversion word takes the first option in braces and looks for the corresponding attribute in the request. %reqAttribute{SOME_ATTRIBUTE} displays the corresponding attribute.
reqCookie{cookie} | Request cookie. This conversion word takes the first option in braces and looks for the corresponding cookie in the request. %cookie{COOKIE_NAME} displays corresponding cookie.
responseHeader{header} | Header of the response. This conversion word takes the first option in braces and looks for the corresponding header in the response. %header{Referer} displays the referer of the response.
requestContent | This conversion word displays the content of the request, that is the request's `InputStream`. It is used in conjunction with a `TeeFilter`, a `javax.servlet.Filter` that replaces the original `HttpServletRequest` by a `TeeHttpServletRequest`. The latter object allows access to the requet's `InputStream` multiple times without any loss of data.
fullRequest | This converter outputs the data associated with the request, including all headers and request contents.
responseContent | This conversion word displays the content of the response, that is the response's `InputStream`. It is used in conjunction with a `TeeFilter`, a `javax.servlet.Filter` that replaces the original `HttpServletResponse` by a `TeeHttpServletResponse`. The latter object allows access to the requet's `InputStream` multiple times without any loss of data.
fullResponse | This conversion word takes all the available data associatede with the response, inclusing all headers of the response and response contents.

Logback access' `PatternLayout` also recognize three keywords, which act like shortcuts to a certain pattern.

keyword | equivalent conversion pattern
--- | ---
common or CLF | %h %l %u %t \"%r\" %s %b
combined | %h %l %u %t \"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\"

The common keyword corresponds to the pattern %h %l %u %t \"%r\" %s %b which displays client host, remote log name, user, date, requested URL, status code and response's content length

The combined keyword is a shortcut for %h %l %u %t \"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\". This pattern begins much like the common pattern but also displays two request headers, namely referer, and user-agent.

### HTMLLayout

The `HTMLLayout` class found in logback-access is similar to the `HTMLLayout` class from logback-classic.

By default, it will create a table containing the following data:

- Remote IP
- Date
- Request URL
- Status code
- Content Length

Here is a sample output produced by `HTMLLayout` in logback-access:

What can be better than a real world example? Our own log4j properties to logback translator makes use of logback-access to showcase a live ouput, using a `RollingFileAppender` and `HTMLLayout`.

What can be better than a real world example? Our own log4j properties for logback translator makes use of logback-access to demonstrate live ouput from `RollingFileAppender` with `HTMLLayout`.

On every new user request to our translator web-application, a new entry will be added to the access logs, which you can view by following this link.