Basic Log4j2 configuration
All Log4j2 configs are written in either XML, JSON, Yaml, or a good old
file. I will be using XML in these examples. The configuration file should be named
log4j2.xml and exist somewhere in your classpath.
A log configuration is surrounded by
tags as seen below. Note the
status attribute in the excerpt below.
As well as your loggers, Log4j creates a
StatusLogger for logging
when loading your configurations etc. In practise you would probably use a configuration status
ERROR, but while setting up a configuration it may be useful to set this to
<?xml version="1.0" encoding="UTF-8"?> <Configuration status="DEBUG" name="example-config"> </Configuration>
When running with the above config, amongst many DEBUG messages, you will notice this warning below indicating that the config is missing a list of Loggers. This is an example of the benefit of using the configuration status setting when building a log config.
2015-02-07 15:47:37,862 WARN No Loggers were configured, using default. Is the Loggers element missing?
java -DLog4jDefaultStatusLevel=DEBUG MyApp
An Example Config File
Let's jump into the deep-end with an example config file, and I'll go through it section by section, explaing the purpose of each construct. Note that this is not necessarily a perfect or great config, but it will demonstrate the fundamentals.
Properties — The
Properties section allows you to define a set
of Key/Value properties that can be used elsewhere in the config file. This is not
a foreign concept. In the example, the
LOG_DIR property demonstrates that
one can refer to System Properties by using the
sys: prefix. There are a
of other prefixes defined
here and here. The
ARCHIVE property then uses the value of the
Appenders — These define possible output methods for loggers in this config.
The appenders are given a
name attribute, which is an any arbitrary identifier.
Console appender shown here, called "STDOUT" will output logs to the standard
output stream, which is your terminal/console usually.
RollingFile appender is very common and useful. It can be configured at
chosen events (based on a Triggering Policy) to stop writing to the current file,
and rather rename/move it. Thereafter it will start writing to a new file of the original
fileName attribute defines the filepath of the active logfile.
filePattern attribute defines the naming scheme of rolled-over files. If
the path does not exist, Log4j will try to create the missing directories. In this case,
the filePattern defines a minutely rollover scheme. The
uses the filePattern to determine when to rotate. Another useful triggering policy is the
SizeBasedTriggeringPolicy which rollsover according to a maximum filesize.
Layouts — These don't have a top-level entry, but they are defined within
every appender. Their purpose is to defines how a log entry is written to a logfile/appender
This example only demonstrates the
PatternLayout. In most common case, your application will write single readable
plain-text lines to a logfile as in this example. The
PatternLayout lets you define the column layout for each line using
called Conversion Patterns. There are other layouts such as
XMLLayout, to name a couple, which are useful respectivle for output to JSON files,
or Network Sockets for example. This obviously depends on the type of Appender.
Loggers — Finally we define actual loggers. In Java code, you will refer
to these loggers by their names. Traditionally these have been named using Java package/class
names, due to the hierarchial additivity in Log4j. This means that entries logged by
a logger named
com.andrew_flower can automatically be logged by a Logger named
com. Whether this occurs, depends on the
Note that there should always be a
RootLogger, and it will actually exist
automatically if not defined. Logs not caught be any other logger will be caught be the
Read the Architecture
for details and examples of parent loggers, levels and additivity.
In the example above the root logger will log all
INFO entries using the
com.andrew_flower.example.Log4jTest logger is more verbose, logging
TRACE (and less verbose levels), but it does so to STDOUT console appender.
here that it specifies
additivity="false", which means that the entry will not be
by parent/ancestor loggers (ie. the
com.andrew_flower.example.Other logger will capture all
pass them along to the
RootLogger. Note that it doesn't specify an appender ref. It
the verbosity for that class.
Using the loggers
Now that we've deconstructed a Log4j2 configuration file in parts and understand, in theory, how it should work, we should test it out with some Java code. Have a look at the following pointless code which uses our config file.
Running the above code will result in two sets of logs, due to our log4j2.xml appender
configuration. Some logs are output to
stdout and others to the file
example1.log. Usually even
INFO lines would go to the file,
but we configured the
xx.Other logger to only send
ERROR (and worse) logs to the
using the additivity attribute.
ERROR 2015-02-10 17:59:14,537 [main] com.andrew_flower.example.Other:<init>(35): log ERROR
TRACE 2015-02-10 17:59:14,532 [main]com.andrew_flower.example.Log4jTest:main(13): entry INFO 2015-02-10 17:59:14,535 [main] com.andrew_flower.example.Log4jTest:main(14): log INFO TRACE 2015-02-10 17:59:14,535 [main]com.andrew_flower.example.Log4jTest:warningMethod(22): entry WARN 2015-02-10 17:59:14,535 [main] com.andrew_flower.example.Log4jTest:warningMethod(23):log WARN TRACE 2015-02-10 17:59:14,536 [main]com.andrew_flower.example.Log4jTest:warningMethod(24): exit ERROR 2015-02-10 17:59:14,536 [main] com.andrew_flower.example.Log4jTest:main(16): log ERROR TRACE 2015-02-10 17:59:14,543 [main] com.andrew_flower.example.Log4jTest:main(18):exit
The code also demonstrates special methods
exit() which are
TRACE entries and helping when debbuging program flow. The
Log4j2Example1 class using a logger that logs very verbosely but only to STDOUT.
For those of you using Apache Maven, you only have to add two dependencies for Log4j2 as shown below. I've also added the Apache repositories containing these dependencies in case you don't have them.
That's the end of this crash course in Log4j2. I wrote this quite quickly, so I hope it makes sense and is helpful in some way. I'll probably be tidying this up as I read it through. I also plan to add some more information about create Log4j plugins and other customizations soon.
Anyways, leave some comments if things are confusing or useful and I'll try respond. Also if you have any questions I'll try to respond.