manual.layouts.html Maven / Gradle / Ivy
Chapter 5: Layouts
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 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.
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 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}
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.
Conversion specifier
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 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 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.
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 ]
%
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.
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]
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") && \
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>
Due to XML encoding rules, the & character cannot be
written as is, and needs to be escaped as &.
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 && 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, 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 value="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 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 willa result in a separate column, in particular for each
literal text in the pattern, 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 value="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 exception stack
traces. In most cases the column will be empty, wasting screen
real-estate. Moreover, printing a stack trace on a separate column
does 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 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 did, 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 you 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>[email protected]</From>
<SMTPHost>mail.domain.net</SMTPHost>
<Subject>LastEvent: %class - %msg </Subject>
<To>[email protected]</To>
</appender>
<root>
<level value="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 value="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
power and flexibility.
Writing your own Layout
Writing a custom Layout for logback access is
nearly identical as its siblingLayout in
logback-classic.
PatternLayout
PatternLayout in logback-access can be configured
in the same way as it's classic counterpart, with the notable
exception of the available conversion specifiers, as appropriate
for HTTP servlet request and response.
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
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.
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 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 HTMLLayout
class found in logback-access is similar to the HTMLLayout class found
in 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 is 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.
You can see the file by following
this link.
Just like any access log, each visit the translator
web-application will add a new entry to the access logs.