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 categories. Using categories it is possible to selectively control which log statements are output at arbitrary granularity.

Is there javadoc documentation for log4j?

What other logging packages are there?

Is there example code for using log4j?

• log4j is optimized for speed.

• log4j is based on a named category 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 priority 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 category.

• 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.

Categories are assigned priorities. A log statement is printed depending on its priority and its category.

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

The PropertyConfigurator defines a particular format of a configuration file. See also the org.log4j.examples.Sort 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 public releases of your code, calling the BasicConfigurator.disable(pri) method will disable all messages of priority pri and below.

For some category cat, writing,

  cat.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(cat.isDebugEnabled()) {
     cat.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
   }

Why was the Category class introduced and how do I migrate from the previous String based implementation?

The reason was speed, speed, speed.

In the former implementation, when evaluating whether a category should be logged or not, we potentially computed a hash and performed an equality check multiple times, once for each higher ranking category. For example, if the category name was "x.y.z", we computed the hash of "x.y.z" and checked if it was already defined (costing an equality check). If not, we parsed "x.y.z" to discover that "x.y" was higher ranking, then computed the hash of "x.y" and checked whether it was defined (costing another equality check). So on, until a valid category was found or there were no possible categories left.

It turns out that for long strings, hash computations and an equality checks are computationally expensive operations.

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 category depending on the current context.

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.

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.

If your extensions are useful then someone will eventually write an extension providing the same or very similar functionality. Your development effort will be wasted.

How fast do bugs in log4j get fixed?

Rather than wait for the next release to be ready, we get bug fixes out of the door as soon as possible. Moreover, once a bug is found or reported, it is treated as fire in the house. All other activities stop until the bug is fixed.

How do I report bugs?