Frequently Asked Questions about log4j

In case of problems with an application, it is helpful to enable logging so that the problem can be located. With log4j it is possible to enable logging at runtime without modifying the application binary. The log4j package is designed so that log statements can remain in shipped code without incurring a high performance cost. It follows that the speed of logging (or rather not logging) is capital.

At the same time, log output can be so voluminous that it quickly becomes overwhelming. One of the distinctive features of log4j is the notion of hierarchical loggers. Using loggers it is possible to selectively control which log statements are output at arbitrary granularity.

Is there example code for using log4j?

• log4j is optimized for speed.

• log4j is based on a named logger hierarchy.

• log4j is fail-stop but not reliable.

• log4j is thread-safe.

• log4j is not restricted to a predefined set of facilities.

• Logging behavior can be set at runtime using a configuration file. Configuration files can be property files or in XML format.

• log4j is designed to handle Java Exceptions from the start.

• log4j can direct its output to a file, the console, an java.io.OutputStream, java.io.Writer, a remote server using TCP, a remote Unix Syslog daemon, to a remote listener using JMS, to the NT EventLog or even send e-mail.

• log4j uses 5 levels, namely DEBUG, INFO, WARN, ERROR and FATAL.

• The format of the log output can be easily changed by extending the Layout class.

• The target of the log output as well as the writing strategy can be altered by implementations of the Appender interface.

• log4j supports multiple output appenders per logger.

• log4j supports internationalization.

Is log4j thread-safe?

What does log output look like?

Here is an example output using PatternLayout with the conversion pattern "%r [%t] %-5p %c{2} %x - %m%n"

176 [main] INFO  examples.Sort - Populating an array of 2 elements in reverse order.
225 [main] INFO  examples.SortAlgo - Entered the sort method.
262 [main] DEBUG SortAlgo.OUTER i=1 - Outer loop.
276 [main] DEBUG SortAlgo.SWAP i=1 j=0 - Swapping intArray[0] = 1 and intArray[1] = 0
290 [main] DEBUG SortAlgo.OUTER i=0 - Outer loop.
304 [main] INFO  SortAlgo.DUMP - Dump of interger array:
317 [main] INFO  SortAlgo.DUMP - Element [0] = 0
331 [main] INFO  SortAlgo.DUMP - Element [1] = 1
343 [main] INFO  examples.Sort - The next log statement should be an error message.
346 [main] ERROR SortAlgo.DUMP - Tried to dump an uninitialized array.
        at org.log4j.examples.SortAlgo.dump(SortAlgo.java:58)
        at org.log4j.examples.Sort.main(Sort.java:64)
467 [main] INFO  examples.Sort - Exiting main method.

Loggers are assigned levels. A log statement is printed depending on its level and its logger.

Log behavior can be set using configuration files which are parsed at runtime. Using configuration files the programmer can define loggers and set their levels.

The PropertyConfigurator defines a particular format of a configuration file. See also the examples/Sort.java example and associated configuration files.

Configuration files can be specified in XML. See log4j.dtd and org.log4j.xml.DOMConfigurator for more details.

See the various Layout and Appender components for specific configuration options.

For some logger l, writing,

  l.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));

incurs the cost of constructing the message parameter, that is converting both integer i and entry[i] to a String, and concatenating intermediate strings. This, regardless of whether the message will be logged or not.

If you are worried about speed, then write

   if(l.isDebugEnabled()) {
     l.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
   }

Can the log output format be customized?

It is simpler to use a nested diagnostic context (NDC). Typically, one would NDC.push() client specific information, such as the client's hostname, ID or any other distinguishing information when starting to handle the client's request. Thereafter, log output will automatically include the nested diagnostic context so that you can distinguish logs from different client requests even if they are output to the same file.

See the NDC and the PatternLayout classes for more information. The NumberCruncher example shows how the NDC can be used to distinguish the log output from multiple clients even if they share the same log file.

For select applications, such as virtual hosting web-servers, the NDC solution is not sufficient. As of version 0.9.0, log4j supports multiple hierarchy trees. Thus, it is possible to log to different targets from the same logger depending on the current context.

Is it possible to direct log output to different appenders by level?

The timestamp is created when the logging event is created. That is so say, when the debug, info, warn, error or fatal method is invoked. This is unaffected by the time at which they may arrive at a remote socket server. Since the timestamps are stored in UTC format inside the event, they all appear in the same timezone as the host creating the logfile. Since the clocks of various machines may not be synchronized, this may account for time interval inconsistencies between events generated on different hosts.

While this is the intended behavior, it only recently became so due to a bug discovery between version 1.0.4 and 1.1b1. Versions 1.0.4 and before had their timestamp regenerated in the converter. In this case the timestamps seen in the log file would all appear in order, generated at the time they arrived at the log server host according to its local clock.

The long answer (and what to do about it): J2EE or Servlet containers utilize Java's class loading system. Sun changed the way classloading works with the release of Java 2. In Java 2, classloaders are arranged in a hierarchial parent-child relationship. When a child classloader needs to find a class or a resource, it first delegates the request to the parent.

Log4j only uses the default Class.forName() mechanism for loading classes. Resources are handled similarly. See the documentation for java.lang.ClassLoader for more details.

So, if you're having problems, try loading the class or resource yourself. If you can't find it, neither will log4j. ;)

Yes. Both the DOMConfigurator and the PropertyConfigurator support automatic reloading through the configureAndWatch APIs. See the API documentation for more details.

The NT Event Viewer relies on message resource DLLs to properly view an event message. The NTEventLogAppender.dll contains these message resources, but that DLL must be copied to %SYSTEMROOT%\SYSTEM32 for it to work properly.

Unfotunately, the logger names are hardcoded within the message resource DLL (see previous question about NTEventLogAppender), so there isn't any easy way to override those dynamically... in fact, I don't think it's possible to do it, as you'd have to modify the DLL resources for every application. Since most native applications don't use the Logger column anyway...

We are very careful not to change the log4j client API so that newer log4j releases are backward compatible with previous versions. We are a lot less scrupulous with the internal log4j API. Thus, if your extension is designed to work with log4j version n, then when log4j release version n+1 comes out, you will probably need to adapt your proprietary extensions to the new release. Thus, you will be forced to spend precious resources in order to keep up with log4j changes. This is commonly referred to as the "stupid-tax." By donating the code and making it part of the standard distribution, you save yourself the unnecessary maintenance work.

Where can I find the latest distribution of log4j?