## Chapter 5: Layouts

Authors: Ceki Gülcü, Sébastien Pennec

| Copyright © 2000-2006, QOS.ch This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 2.5 License .

## 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 class 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 extends ContextAware, LifeCycle {

      String doLayout(Object event);
      String getHeader();
      String getFooter();
      String getContentType();
    }

This interface is rather simple and yet is sufficent for many formatting needs.

## Logback classic

Logback classic only processes events of type `ch.qos.logback.classic.LoggingEvent`. Therefore, classic extends `Layout` to accept only `LoggingEvent` objects.

The extending interface is called `ClassicLayout`, as shown below.

    public interface ClassicLayout extends Layout {

      String doLayout(LoggingEvent event);

    }

### PatternLayout

Logback classic ships with a flexible layout called `PatternLayout`, which implements the `ClassicLayout` interface. As all classic layouts, `PatternLayout`

takes a logging event and returns a String. However, the returned String can be modified at will by tweaking its conversion pattern.

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 (examples/chapter5/PatternSample.java)

    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 appender = new ConsoleAppender();
        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.

As mentionned previously, certain conversion specifiers can include optional parameters which are declared between braces following the conversion word. A sample conversion specifier with options could be %logger{10}.

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

Conversion Word | Effect
--- | ---

c{length}
l{length}
lo{length}
logger{length}

Used to output the logger name of the logging event.

The logger name conversion word can take an integer as a first option. The converter's abbreviation algorithm will shorten the logger name without significant loss of meaning.

The next table should clear things up.

Conversion Pattern | Logger name | Result
--- | --- | ---
%logger | mainPackage.sub.sample.Bar | mainPackage.sub.sample.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, this word can take an interger as it's first option and use its abbreviation algorithm to shorten the class name.

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.

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 ISO8601 in the braces. If no option is set, the converter uses ISO8601 as a default value.

Here are some sample option values. They assume that the actual date is Friday 20th of October, 2006 and that the reader finished her 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 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

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. This behaviour is justified by the fact that displaying caller data is rather expensive, and one should generally not want to display it.

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 MDC class for more details.

ex{length}
throwable{length}

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.

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. This behaviour is justified by the fact that throwable data is generally displayed unless the evaluator would return a positive value. Evaluators are described further down this document.

% | 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 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 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. 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 category 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.

Here are some examples of the format modifier truncation:

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]

### Option handling

A conversion specifier can be followed by options between braces. We have already seen some of the possibilities offered by logback's option handling with, for example, the MDC conversion specifier: %mdc{someKey}.

However, there is more to it than that.

ADD OPTIONS EXAMPLES

#### Evaluators

Another very useful way of adding options to a conversion specifier is when `PatternLayout` is used with `EventEvaluators` .

`EventEvaluators` have the responsability to check wether a given event matches a given criteria.

Let's look at an example using `EventEvaluators` . The following configuration file outputs the logging events to the console, displaying date, thread, level, message and caller data.

Since displaying the caller data of a logging event is rather expensive, this information will be displayed only when the logging request comes from a specific logger, and whose message contains a certain string. By doing that, we make sure that only the most important logging requests will have their caller information generated and displayed, without penalizing application performance.

Here is how to configure logback to behave like we described:

Example 5.2: Sample usage of EventEvaluators (examples/chapter5/callerEvaluatorConfig.xml)

    <configuration>
      <evaluator name="DISP_CALLER_EVAL">
        <Expression>logger.getName().contains("chapter5") &amp;&amp; \
          message.contains("stacktrace")</Expression>
      </evaluator>

      <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}%n" />
        </layout>
      </appender>

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

Please note that the & value cannot be written like one would do in a java class, because of XML format encoding.

Let's test this configuration with the following code.

Example 5.2: Sample usage of EventEvaluators (examples/chapter5/EventEvaluatorExample.java)

    public class CallerEvaluatorExample {

      public static void main(String[] args)  {
        Logger 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("stacktrace logging statement" + i);
          } else {
            logger.debug("logging statement" + i);
          }
        }
      }
    }

This excerpt does nothing very fancy. Five logging requests are issued, the third one being different from the others.

When a logging request is sent, the corresponding logging event will pass through the evaluation process. Here, obviously, the third request will match the evaluation, causing its caller data to be displayed.

Here is the output of the `EventEvaluatorExample` class.

    0    [main] DEBUG - logging statement0
    0    [main] DEBUG - logging statement1
    0    [main] DEBUG - logging statement2
    0    [main] DEBUG - stacktrace logging statement3 Caller+0	 \
      at chapter5.CallerEvaluatorExample.main(CallerEvaluatorExample.java:28)

    0    [main] DEBUG - logging statement4

Of course, one can change the expression to match one's specific situation. An expression testing logger name and request level could also be meaningful: all logging requests of level WARN and up, coming from a sensible part of an application like a financial transaction module, would have their caller data displayed.

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

Let's look at a different situation. When exceptions are added to a logging request, they are usually displayed. However, in some cases, one might want some exceptions never to be displayed.

The java code shown below is creating five log requests, each one with an exception. However, we do not want request number 3 to display its exception in the logging output.

    public class ExceptionEvaluatorExample {

      public static void main(String[] args) {
        Logger 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 allow that.

Example 5.3: Sample usage of EventEvaluators (examples/chapter5/exceptionEvaluatorConfig.xml)

    <configuration>

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

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

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

With this configuration, each time an instance of the chapter5.TestException will be associated with a logging request containing an exception, no information will be displayed about the exception.

Important: With the ex conversion specifier, the data is displayed when the expression passed to the evaluator is false.

### HTMLLayout

HTMLLayout outputs events in an HTML table. Each row of the table corresponds to an event.

The content of the table columns are specified using a conversion pattern. See `PatternLayout` for documentation on the available patterns.

One notable point about the use of `PatternLayout` with `HTMLLayout` is that conversion specifiers should not be separated by a space. Each specifier found in the pattern will result in a separate column, meaning that spaces will create empty columns.

The pattern %ex used to display an Exception is not the only way to display an Exception with this layout. If you use this pattern, a table column will be created to display the potential Exception's stacktrace.

However, a better solution is available in the form of implementations of the `IThrowableRenderer` interface. These implementations can be called and assigned to HTMLLayout to manage the display of anything related to Exceptions.

By default, a `DefaultThrowableRenderer` is assigned to the HTMLLayout. It writes the Exception on a new table row, along with its stacktrace, in a easily readable manner.

If one wants to use the &ex pattern anyway, then a `NOPThrowableRenderer` can be specified in the configuration file.

A user-specified external CSS file can be linked to the html page. In case one does not want to customize the html output, an internal CSS style is used. In that case, the following xml element can be nested into the `<layout>` element.

    <layout>
      ...
      <cssBuilder class="ch.qos.logback.core.helpers.CssBuilder">
        <param name="url" value="path_to_StyleFile.css" />
      </cssBuilder>
      ...
    </layout>

The HTMLLayout is often used in conjunction with SMTPAppender, to send a nicely formatted html email. Of course, it can be used with any other Appender.

When one wants to use the HTMLLayout with a SMTPAppender, the following configuration is typically used.

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

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

In this configuration file, the throwableRenderer element specifies the default implementation of IThrowableRenderer. It could be omitted, but is showed for educationnal purposes.

## Logback access

Just like `ClassicLayout` represents the `Layout` interface for the classic module, the `AccessLayout` exists for the access module. It's implementation is very straight-forward.

    public interface AccessLayout extends Layout {

      String doLayout(AccessEvent event);

    }

Many access layouts are actually adaptations of classic layouts. Logback modules classic and access address pretty different needs, but offer the same power and flexibility to the user.

### PatternLayout

Access' `PatternLayout` work the exact same way as it's classic counterpart.

However, the conversion specifier are different, giving specific access to request and response objects' attributes.

Here are the conversion specifier one can use with logback access `PatternLayout`.

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.
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 can also be used. 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.

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

common or CLF

combined

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 to %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 access version of `HTMLLayout` works like logback classic's version.