Apache Log4j

Log4J: A logging framework for J2EE

Log4j homepage: http://jakarta.apache.org/log4j/

Reference book on log4j:

The Complete Log4j Manual by Ceki Gulcu Edition: Paperback

Introduction
Log4j is an open source tool (OSS) developed for inserting logs statements into your application and was developed by people at Apache fundation. It’s speed and flexibility allows log statements to remain in shipped code while giving the user the ability to enable logging at runtime without modifying any of the application binary. All of this while not incurring a high performance cost/loss.

Requirements

• Log4j need at least a compatible JDK 1.1.x to run.
• The DOMConfigurator is based on the DOM Level 1 API. The DOMConfigurator.configure(Element) method will work with any XML parser that will pass it a DOM tree. The DOMConfigurator.configure(String filename) method and its variants require a JAXP compatible XML parser, for example Xerces or Sun’s parser. Compiling the DOMConfigurator requires the presence of a JAXP parser in the classpath.
• The org.apache.log4j.net.SMTPAppender relies on the #JavaMail API. It has been tested with #JavaMail API version 1.2. The #JavaMail API requires the #JavaBeans Activation Framework package.
• The org.apache.log4j.net.JMSAppender requires the presence of the JMS API as well as JNDI.
• Log4j test code relies on the JUnit testing framework in order to maintain quality of release.

Why inserting log statement or rely on this (old) technology?

Why choosing Log4J? (From apache.org)

• log4j is optimized for speed. The system write has been rewrite for efficiency and is now asynchrone (compare to System.err)
• log4j is based on a named logger hierarchy. (category)
• log4j is fail-stop but not reliable.
• log4j is thread-safe. No interblocking thread, or memory leaks.
• 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. (Appenders)
• 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.
• It is used extensively by thousands of #Java developers. If a flaw is discovered it gets fixed in the next release.
• The log4j code is likely to be better than code you’d write yourself and is l ikely to improve over time.
• Ports to other languages are: C++, Eifel, Perl, .NET, Python, Ruby…more than 57 languages are supported

Log4j concepts

Using Log4j in your code

It is not recommended to use log4j api directly, since who knows if a better logging framework won’t do better in the future or if log4j won’t modify its api’s. The main idea is that when you aquire a 3rd party component, is to build a wrapper around it. It is even better if the wrapper contains an abstract factory: maybe in some case you wil have to use different class of logging (because of performance, licence…)

Log4j Guidelines
The FAQ of log4J is a must to read, here are the most important points:

1. Respect Levels!
   Respect levels and categorize the logs according to severity and messages size. Please define a special logger (restricted to a package) that can be switch off and that do not write to much statement in log output.
2. Meaningful statements
   Create code with System.err.println or System.out.println If you are doing some internal reviews of your code, please try to write some meaningful information in logs. Avoid log of type: “I am here”, “here 1”, “here 2” and so on..
3. Classwide static logger
   It is recommended to provide a class wide logger access point, if you need to do a lot of output in a class or hierarchy. Define a protected Logger in the parent hierarchie
   

   public class Mamals { protected static LoggerWrapper logger = LogFactory.getLog(Mamals.class); … }

   and use it in all children

   public class Human extends Mamals { public Human() { super(); logger.debug(“init”); } }

4. Increase speed
   Log4J is not slow, it is even faster than System.out or System.err (System.err or System.out are synchronous while NOT with log4j, the cost in times comes more from costs during formating messages!
   If you know that you must heavily formatted the output message, do not use the following:
   

   l.debug(“Cash balance is ” + cashvalue);

   use instead

   if(myLogger.isDebugEnabled()) { myLogger.debug(“Cash balance is ” + cashBalance.toXML()); }

5. How to name Loggers?
   You can name loggers by locality. It turns out that instantiating a logger in each class, with the logger name equal to the fully-qualified name of the class, is a useful and straightforward approach of defining loggers. This approach has many benefits:

• It is very simple to implement.
• It is very simple to explain to new developers.
• It automatically mirrors your application’s own modular design.
• It can be further refined at will.
• Printing the logger automatically gives information on the locality of the log statement.

However, this is not the only way for naming loggers. A common alternative is to name loggers by functional areas. For example, the “database” logger, “RMI” logger, “security” logger, or the “XML” logger. You are totally free in choosing the names of your loggers. The log4j package merely allows you to manage your names in a hierarchy. However, it is your responsibility to define this hierarchy. Note by naming loggers by locality one tends to name things by functionality, since in most cases the locality relates closely to functionality.

Remote logging over TCP
Read carefully: http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/net/SocketAppender.html and
http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/net/SocketHubAppender.html

Starting the server .Chainsaw
Chainsaw is a graphical logging client, where you can see, sort and filter logs data.
Documentation can be read here: http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/chainsaw/package-summary.html and it is a part of log4j.jar

1. Log4 gives you the ability to send messages to a remote location over a socket for logging purposes. The org.apache.log4j.net.SocketAppender and org.apache.log4j.net.SocketServer classes are the key classes used in remote logging.
2. Modify all logger in your log4j.xml to use a SocketApender as appender, Once you have loaded this configuration, all messages will be written to the machine and port that you specify.
3. Start the client application (Chainsaw), this program will receive logs and show them in a swing GUI

On the server side (where your application create logs), you will need to run log4j’s SocketServer class. You can create a configuration file with configuration information similar to the following: The whole applcation is in DEBUG mode

1. Set up your CLASSPATH on both the client and server to contain log4j.jar
2. Run the SocketServer at the command line. The command line syntax for the SocketServer is as follows:
   java org.apache.log4j.net.SocketServer portNumber configurationFile configurationDirectory
   start the server:

Start your application, without doing any change in your code or recompiling it, you can now log data remotely!

Configuring log4j

Location of configuration file
The configuration files of log4j must be in classpath, if more than one are in classpath, the first found will be used. Log4j require to have a compatible parser in classpath in order to read the configuration file. As default, Logj use Crimson.jar

Location of DTD
The DTD is needed in order to initialize log4j, 2 solutions are available:

Extending log4j

Defining your application specific loggers, appenders and layouts
You can look at the Log4j API to see how to implement a logger, appender and layout.

Conclusions

One of the strength of log4j is that is do not require to recompile the java code to binary classes to change considerably the ouput amount in logs. You can add logging statements in your code, and without changing the code shipped, change at runtime the amount of log output. Thus the major behaviour logging strategies are done in this file (it can be a properties file or a XML file). You should store this file in the classpath of your application.

Annexes

Example of configuration files:

Resources

• Join the #Eclipse Platform community and download the Platform at eclipse.org. The #Eclipse Platform source code is licensed under the Common Public License. At eclipse.org, you’ll also find a glossary of terms and descriptions of #Eclipse projects, along with technical articles and newsgroups. The #Eclipse Platform white paper details the major components and functions of #Eclipse.
• http://jakarta.apache.org/log4j/ Homepage:
• http://jakarta.apache.org/log4j/docs/api/index.html JAVADOC:
• http://jakarta.apache.org/log4j/docs/FAQ.html FAQ:
• http://www.onjava.com/pub/a/onjava/2002/08/07/log4j.html?page=1 Tutorials
• http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/performance/Logging.html Read the following, it show difference of speed among appenders and layout, Performance of logging when logging is turned on is determined by the cost of walking the logger hierarchy. Typical cost of a hierarchy walk is in the range 5 to 15 microseconds. Actual logging is in order of 100 to 300 micro-seconds.