Mr N

Apache log4j is a logging API library implemented in Java. It was built to replace the built-in Java logging libraries which are a bit restrictive.

Log4j consists of 3 components: Loggers, Appenders and Layouts.

Logger
A logger is an object that log messages are submitted to. The logger will decide whether to display the message by comparing the levels. Loggers are hierarchical and settings are inherited from parent loggers. The top level (root) logger is called “rootLogger” and the user may create their own hierarchy below it. The hierarchy is constructed from the dots in logger names. In almost all cases the logger name is the package and full name of the class. So for example “uk.co.bigsoft” is the parent logger of “uk.co.bigsoft.myapp” such that “uk.co.bigsoft.myapp” inherits all its settings from “uk.co.bigsoft".

Appenders
An appender is an output destination. A logger may have more than one appender. If the message passes the criterion for output (on that logger) it will be sent to all the appenders on each node of the hierarchy up to the rootLogger.

Layouts
The layout decides the format of the output. C-style printf tokens are used to build the output message.

Configuration
Now that we understand what each of the bits are called and what they are supposed to do. We can take a look at plugging them together. In its simplest form, a logger definition is just a logger level followed by a list of appenders.

log4j.rootLogger=info, screen, appender2
log4j.jacorb=warn, appender3
log4j.uk.co.bigsoft.myapp=all, appender3

Above I have defined 3 loggers.

• Any message destined for a logger called “jacorb” that has a level of warn or higher will be sent to appender3 for output. After this logger has dealt with the message it is sent to the parent logger for handling, which in this case is the rootLogger. If the message level is higher than info it will be sent to the appender screen and then appender2.
• Any message destined for a logger called “uk.co.bigsoft.myapp” will be sent to appender3 for output. The message will then be sent to the rootLogger for handling.
• Any message sent to an undefined logger will be handled by the rootLogger.

Logging Levels
A logging definition contains a logging level which is used as a filter. Listed below are the standard logging levels which you get “out of the box". One can create intermediate levels if you want but it’s not worth the effort!

• OFF - the highest possible rank and is intended to turn off logging.
• FATAL - level designates very severe error events that will presumably lead the application to abort.
• ERROR - designates error events that might still allow the application to continue running.
• WARN - designates potentially harmful situations.
• INFO - designates informational messages that highlight the progress of the application at coarse-grained level.
• DEBUG - designates fine-grained informational events that are most useful to debug an application.
• TRACE - designates finer-grained informational events than the DEBUG
• ALL - lowest possible rank and is intended to turn on all logging.

Defining Appenders
An appender is defined like this:

log4j.appender.appender_name=appender_class

where appender_name is the name of the appender and appender_class is the fully qualified name of the class which does the work (it must implement org.apache.log4j.Appender if you want to write your own).
An appender can have several sub properties, but most of them will depend on the type of appender.

org.apache.log4j.ConsoleAppender
Has no parameters.

org.apache.log4j.RollingFileAppender

File	Full path of output file
MaxFileSize	Maximum size of a file. You can specify unit e.g. 100KB
MaxBackupIndex	Rotate to log, but only keep this many files

Defining Layouts
The layout of the appender is tacked on to the back of the appender. So using our example above:

log4j.appender.appender_name.layout=layout_class

where layout_class is the fully qualified name of the class which does the work (it must implement org.apache.log4j.Layout if you want to write your own).
A layout can have several sub properties, but most of them will depend on the type of layout.

org.apache.log4j.PatternLayout
This layout is used most of the time and only has one property that you can set: ConversionPattern.

log4j.appender.appender_name.layout=org.apache.log4j.PatternLayout
log4j.appender.appender_name.layout.ConversionPattern=%d %p [%c] - %m%n

The ConversionPattern lets you specify C-style printf tokens which build the output message:

%c{n}	Category of the logging event. Optional number *
%C{n}	Class of the logging event. Optional number *
%d{format}	Date / Time.
%F	Filename.
%l	Caller of logging message.
%L	Line of code where the message came from.
%m	Message text.
%M	Method that called the logger.
%n	New line.
%p	Level of the log statement.
%P	Priority of log message.
%r	Number of milliseconds elapsed since the start of the program.
%t	Name of the thread making the log request.
%x	Nested diagnostic context associated with the thread.
%X	Mapped diagnostic context associated with the thread.
%%	Percent character.

% tokens may be padded using C-style notation:

%-4r	Field is 4 characters wide padded on the left with spaces.
%4r	Field is 4 characters wide padded on the right with spaces.
%04r	Field is 4 characters wide padded on the right with zeros.

{n} Optional numbers cut down dotted output e.g. uk.co.bigsoft.myapp.gui represented as %C{2} would produce myapp.gui.
PatternLayout API pages gives the full rules.

Other layouts include
Other layouts include DateLayout, HTMLLayout, PatternLayout, SimpleLayout, XMLLayout.

Configuration file
Bizarrely the log4j manual doesn’t describe how to create a log4j properties file. It gives a couple of examples and describes how they are suppose to work, then expects you to infer the knowledge by osmosis.

I think learning by osmosis is a bit tricky, so for everyone else here are a couple of pointers.

The default file name is log4j.properties and is picked up from the classpath.

All properties in the log4j.properties configuration file start with log4j.

English version of:
http://logging.apache.org/log4j/1.2/manual.html

---

Above I described how to configure Appenders, which are just a log message destination. Here is an example of using the logging system to send messages to a Java Message Service:
How do I use log4j JMS appender with ActiveMQ