Chapter 5: Layouts
In order to run the examples in this chapter, you need to make sure that certain jar files are present on the classpath. Please refer to the setup page for further details.
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.
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:
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 value="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 with Joran". 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 value="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.
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 backslahes, as in "\\(" and "\\)". In practice however, only the opening 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} l{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 first and only option. The converter's abbreviation algorithm will shorten the logger name, usually without significant loss of meaning. The next table provides examples of the abbreviation algorithm in action.
|
||||||||||||||||||
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. 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 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.
|
||||||||||||||||||
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} throwable{length} ex{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. 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:
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. |
||||||||||||||||||
marker |
Used to output the marker associated with the logger request. If there is a single marker available, its name is displayed. In case the marker has children markers, the converter displays the parent's and children's names as shown below. parentName [ child1, child2 ] |
||||||||||||||||||
% | The sequence %% outputs a single percent sign. |
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 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}.
A conversion specifier might have more than one options. For example, a conversion specifier that uses evaluators, which we will cover very soon, simply adds the 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
Another use case for adding options to a conversion
specifier is when
PatternLayout
is used with
EventEvaluator
objects.
EventEvaluator
objects
have the responsability to check wether a given event
matches a given criteria.
Let's look at an example using
EventEvaluator
objects.
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 specific 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 (logback-examples/src/main/java/chapter5/callerEvaluatorConfig.xml)<configuration> <evaluator name="DISP_CALLER_EVAL"> <Expression>logger.getName().contains("chapter5") && \ message.contains("who calls thee")</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}" /> </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 encoding rules.
Let us test this configuration with the following 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 above application does nothing too 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, the third request will match 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 match a real world 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 evaluates to true.
Now, let us look 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 specific exception.
The java code shown below creates five log requests, each one with an exception. However, we do not want to have the stack trace of the third request to be output.
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 allow that.
Example 5.3: Sample usage of EventEvaluators (logback-examples/src/main/java/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 is included within a logging request, no stack trace will be displayed.
Important: With the %ex conversion specifier, the data is displayed when the expression evaluates to false.
Creating a custom conversion specifier
We've seen up to here quite a lot of possibilities with conversion specifier and
PatternLayout
objects. But what if somebody wants to make her own conversion
specifier?
In that case, two steps are needed.
First, one must implement her own Converter
class.
Converter
objects are responsible to extract a specific information out of
a LoggingEvent
. When %logger is used, a
LoggerConverter
is called to extract the name of the logger from the LoggingEvent
.
Let us say that our customized Converter
will output the level of the logging
event, colored following ANSI rules. Here is the necessary implementation:
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 ""; } } }
This implementation is quite straightforward. The MySampleConverter
class
extends ClassicConverter
, and implements the convert
method.
In that method, all it has to do is return the appropriate information.
The second step, once the Converter
class done, is to let logback know about
the new Converter
. For this task, we just need to declare the new
conversion word in the configuration file, as shown below:
<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 value="debug" /> <appender-ref ref="STDOUT" /> </root> </configuration>
In this configuration file, once the new conversion word has been declared, we
just use it within a PatternLayout
pattern element, as if
our custom conversion word had always been here.
The intersted reader might want to take a look at other Converter
implementations
like
MDCConverter
to learn how to implement more complex behaviours, involving
the use of options, in her custom Converter
objects.
HTMLLayout
HTMLLayout
outputs events in an HTML table. Each row of the table corresponds to a
logging event.
Here is a sample of the output that can be obtained using HTMLLayout
along with the default CSS stylesheet:

The content of the table columns are specified using a
conversion pattern. See PatternLayout
for documentation on
the available patterns. This ensures that the user has full control over the creation
of the html table. One can choose to display any (or all) data that PatternLayout
can provide.
One notable point about the use of PatternLayout
with HTMLLayout
is that conversion specifiers should not be separated by a space or in general
any literals. Each specifier found in the
pattern will result in a separate column, meaning that each literal will create
an extra column.
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. That means that, in most cases, the column will be empty, and will take quite a lot of space when displaying an exception's stack trace.
Since printing a stack trace on a separate column is not very readable,
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, like presented in the picture above.
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 that case, the following
xml element can be nested into the <layout>
element.
<layout> ... <cssBuilder class="ch.qos.logback.core.html.UrlCssBuilder"> <param name="url" value="path_to_StyleFile.css" /> </cssBuilder> ... </layout>
In case one does not want to customize the html output, an internal CSS style is used.
The HTMLLayout
is often, although not necessarily used in conjunction with
SMTPAppender
, to send a nicely formatted html email.
When one wants to use the HTMLLayout
with a
SMTPAppender
,
the following configuration would be typical.
<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> <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>
HTMLLayout
can also be used with any FileAppender
. In that
case, one can specify a rolling policy to archive log messages automatically.
One real world example could use the 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 value="debug" /> <appender-ref ref="FILE" /> </root> </configuration>
Logback access
Many access layouts are mere adaptations of classic layouts. Logback classic and access modules address different needs, but offer comparable power and flexibility.
Writing your own Layout
Writing a custom Layout
for logback access is nearly identical
as to writing a Layout
for the classic module.
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. 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
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 |
fullRequest |
This conversion word takes all the available headers of the request and displays their values. |
responseContent |
This conversion word displays the content of the response, that is the
response's |
fullResponse |
This conversion word takes all the available headers of the response and displays their values. |
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.
By default, it will create a table containing the following data:
Remote IP
Date
Request URL
Status code
Content Length
Here is what you can expect from a configured access HTMLLayout
:

What's better than a real world example? Our own log4j properties to logback configuration
translator
is using logback access to showcase a live ouput, using a RollingFileAppender
and
access' HTMLLayout
.
You can see the file by following this link.
Just like any access log, it can be altered simply by visiting the translator application.