When it comes to logging in Java™ there is no shortage of alternatives. The one I’ve used the most is log4j by the Apache Foundation. In its basic usage it has no dependencies and you only need to add the ones you’ll use like SMTP support for mailing loggers, JSON configuration support or a JDBC connector to log to your favorite database. The newest version even allows asynchronous logging through the LMAX Distruptor interthread messaging API that promises greater throughput than concurrent queues and lock based thread synchronization.

Since the 2.x version came out, however, the documentation for the 1.x versions has become fragmented. There are dead links everywhere and the XML configuration method reference is not even half complete. A common question about the XML format is about validation. A more thorough search can land you on the source control version of the DTD. Let’s go through the details of what makes a valid log4j XML configuration file.

The document starts like any other XML, with the declaration, the doctype and the root element:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">

Then comes a series of child elements which must be in the order:

renderer

Renderers help define the way objects of one class are turned into strings. The element takes two attributes, the rendered class name and the renderer class name. Both of these are fully qualified class names like java.lang.Object, or java.util.Date. Renderers are objects that extend the interface org.apache.log4j.or.ObjectRenderer.

throwableRenderer

These renderers are similar the regular renderers but are used to convert exceptions to strings. They have the same attributes but can also take additional parameters in <param> child nodes. The renderer is optional and there can be only one.

appender

An Appender take log statements and output them somewhere. They can write them to files, consoles, databases or mail them. There are default implementations to send them to these and other destinations. These must have a name so they can be referenced elsewhere and the class name of the implementation. Appenders are configured mainly through <param> elements where the parameter name corresponds to the object property where the value will be stored, like the RollingFileAppender‘s file name or maximum size. They can reference each other using <appender-ref> tags which use the appender names to refer to each other.

plugin

The presence of this element in the 1.x DTD is a mystery to me since plugins are a 2.x feature. They can be safely ignored if you’re using 1.x.

category or logger

Category was replaced by logger around 2000 but they may still be around in config files and can be considered interchangeable. They are mainly used to link loggers to appenders using <appender-ref> tags.

root

This element behaves the same way as a logger but refers to the root logger and has no class or name attributes.

categoryFactory or loggerFactory

This element is optional and there can be only one logger factory defined. It has the attribute class where the fully qualified name of the class is specified and can have any number of child <param> elements to further customize the factory. If no factory is defined the default factory will be used unless one is created programmatically.

A full example may look like this:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

<log4j:configuration 
    xmlns:log4j="http://jakarta.apache.org/log4j/"
    threshold="all"
    debug="false"
    reset="false" >
    
    <renderer 
        renderedClass="com.example.dto.PersonDTO" 
        renderingClass="com.example.render.PersonRenderer" />
    <renderer 
        renderedClass="com.example.dto.CatDTO" 
        renderingClass="com.example.render.CatRenderer" />

    <throwableRenderer class="org.apache.log4j.EnhancedThrowableRenderer" >
        <!-- <param name="" value="" /> -->
    </throwableRenderer>

    <appender name="console"
              class="org.apache.log4j.ConsoleAppender">
        <param name="Target" value="System.out"/> 
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%-5p %c{1} - %m%n"/>
        </layout>
    </appender>

    <logger name="com.example.db.Connection"
            additivity="false" >
        <level value="warn" />
    </logger>

    <root>
        <level value="severe" />
        <appender-ref ref="console" />
    </root>

    <loggerFactory class="com.example.MyLoggerFactory">

    </loggerFactory>
        
</log4j:configuration>