Log4j XML Configuration Primer
Below is a basic xml configuration file for log4j that will get you started:
This will print all debug or higher messages to the console/screen. Items of note:
- The appender is defined first, with a name (in this case "console"). A layout is defined for the appender (in this case ), and a pattern is defined for the layout. What is required for the layout is layout specific, so check the javadoc description for the layout class you choose to use ( is used most commonly).
- No loggers are defined in this example, but the configuration for the "root" logger is defined. It is configured to level debug, and the appender named "console" is attached to it. All loggers inherit from root, so in this example, all debug or higher messages from all loggers will be printed to the console appender.
XML Configuration Format
In order to better understand the more detailed examples, it is useful to understand the expected format for the xml configuration files. This is defined by the log4j.dtd which is located in the log4j distribution jar in the package org.apache.log4j.xml. The contents of this file will not be listed in its entirety, so please feel free to open/print the file yourself. If you are not familiar with xml dtd file formats, then you should go find a good book on that subject first.
Near the beginning of the file is the following declaration:
This element defines the expected structure of the xml configuration file: 0 or more renderer elements, followed by jocuri barbie0 or more appender elements, followed by 0 or more logger elements, followed by 0 or 1 root element, followed by 0 or 1 categoryFactory element. If this order is not followed, then errors will be printed by the xml parser at the time the xml file is read in. Also, as a note, the "category" element is the same as the logger element. Prior to log4j version 1.2, loggers were known as category. Much of the documentation still refers to category. Just understand that they are the same thing.
Further along in the log4j.dtd is the following declaration which defines the allowed attributes:
- debug - Probably the most important attribute for log4:configuration, setting it to "true" will print out information as the configuration file is read and used to configure the log4j environment. Very useful when trying to fiure out why your configuration file is not doing what you expect.
- threshold - <yet to be described>
Understanding the expected structure of the xml configuration file makes it easier to concentrate on the specific elements one needs to configure.
One can instrument all the code one writes to output useful debug trace messages, but if log4j is not configured to have at least one appender, all will be for naught. None of the useful messages will be displayed anywhere.
Looking again to the log4j.dtd, appender elements are declared to be:
An appender element must have name and class attributes. The name is the value used to reference the appender in the rest of the configuration file. The class attribute should be the fully qualified class name of the appender class to use (ie
An appender element can also contain child elements:
- 0 or 1 errorHandler element - <yet to be described>
- 0 or more param elements - Each appender can be configured with setting specific to the functioning of the appender. This is implemented by getter and setter methods in the appender class. The param element is used to access the setter methods. The format for param elements is simple; they are atomic elements with a name attribute and a value attribute. The name attribute should be the name of the setter method with the "set" part of the method name omitted (ie method name "setTarget" would be "Target"). The value attribute is the value the setter method should be set with.
- 0 or 1 layout element - Not all appenders use or require a layout. For appenders that do, the layout element defines what layout class to use. The layout element has one attribute, class, which is the fully qualified class name of the layout class to use. Similar to the appender element, the layout element is allowed to have 0 or more param child elements. Again, the param elements are used to set specific values for the layout class, which varies based on what layout class is used.
- 0 or more filter elements - See the Filter Configuration section below for more details.
- 0 or more appender-ref elements - <yet to be described>
So, from the above, the simple example of the appender named "console" from the basic example starts to make more sense:
The name of of the appender is "console" and this is the name that is used to refer to the appender in the rest of the configuration file. The class to use for the appender is
The console appender has one param element defined. Looking at the javadoc for
method is used to choose which console stream to print messages to, System.out or System.err. The example configures the appender to use System.out.
The console appender also has a layout element defined which uses
. Looking at the javadoc for
setConversionPattern method takes a string describing the layout for messages. The details of this format can also be found in the javadoc.
The details of the configuration for a specific appender class vary from class to class. Your best bet is to review the javadoc for the appender class you want to use. Pay particular attention to the setter property methods and the values they expect. Each setter method can be accessed using the param element in the xml configuration.
Currently, the following appender classes exist:
Now the appenders are configured. But how to configure loggers to output messages at a certain level? How to configure loggers to output to specific appender? Welcome to logger configuration.
The most important logger you need to configure is the root logger. From the simple example, this was done with the following configuration:
The root logger is configured to output log message at level "debug" or higher to the appender named "console". All loggers inherit their settings from the root logger, so with no other configuration settings, all loggers will output all of their messages to the "console" appender automatically. This may be fine for simple debugging, but eventually more specific logger configuration is going to be required.
Looking again to the log4j.dtd, logger elements are declared to be:
A logger element must have a name attribute. This is the name of the logger used when creating the Logger instance(usually the fully qualified class name). It can also have an optional additivity attribute. More on this later.
A logger element can also contain child elements:
- 0 or 1 level element - This defines the level of log messages that will be allowed to be logged for this logger. Normal usage has a value of "debug", "info", "warn", "error", or "fatal". Only that level or above will be reported to the log.
- 0 or more appender-ref elements - This references a defined appender that log messages from this logger should be directed to. Appender-ref elements are simple elements that have a ref attribute. The value for this attribute should be the name of the appender.
A typical logger configuration element would look similar to this:
<yet to be described>
The output of a log statement of logger C will go to all the appenders in C and its ancestors. This is the meaning of the term "appender additivity".
However, if an ancestor of logger C, say P, has the additivity flag set to false, then C's output will be directed to all the appenders in C and it's ancestors upto and including P but not the appenders in any of the ancestors of P.
Loggers have their additivity flag set to true by default.
Additivitiy section taken from http://logging.apache.org/log4j/docs/manual.html.
Converting Configuration Files To XML format
I have converted the configuration examples from the log4j manual to xml format. Hopefully people can use this to convert their own configuration files.
Filters can be defined at appender level. For example, to filter only certain levels, the LevelRangeFilter can be used like this:
<yet to be described>
(Please feel free to add your own configuration examples here)
Note that TimeBasedRollingPolicy can only be configured with xml, not log4j.properties