Logging within the context of program development constitutes inserting statements into the program that provide some kind of output information that is useful to the developer. Examples of logging are trace statements, dumping of structures and the familiar System.out.println or printf debug statements. log4j offers a hierarchical way to insert logging statements within a Java program. Multiple output formats and multiple levels of logging information are available.

By using a dedicated logging package, the overhead of maintaining thousands of System.out.println statements is alleviated as the logging may be controlled at runtime from configuration scripts. log4j maintains the log statements in the shipped code. By formalising the process of logging, some feel that one is encouraged to use logging more and with higher degree of usefulness.

In order to use the tools we are about to install it is necessary to setup the operating environment so that the tools know where to find stuff they need and the operating system knows where to find the tools. A understanding of how to do this is essential as you will be asked to change the operating environment. I have comprehensively covered this in documents entitled

The use of log4j revolves around 3 main things:

 

The logger is the core component of the logging process. In log4j, there are 5 normal levels Levels of logger available (not including custom Levels), the following is borrowed from the log4j API (

• static Level DEBUG

  The DEBUG Level designates fine-grained informational events that are most useful to debug an application.

• static Level INFO

  The INFO level designates informational messages that highlight the progress of the application at coarse-grained level.

• static Level WARN

  The WARN level designates potentially harmful situations.

• static Level ERROR

  The ERROR level designates error events that might still allow the application to continue running.

• static Level FATAL

  The FATAL level designates very severe error events that will presumably lead the application to abort.

In addition, there are two special levels of logging available: (descriptions borrowed from the log4j API http://jakarta.apache.org/log4j/docs/api/index.html):

• static Level ALL

  The ALL Level has the lowest possible rank and is intended to turn on all logging.

• static Level OFF

  The OFF Level has the highest possible rank and is intended to turn off logging.

The behaviour of loggers is hierarchical. The following table illustrates this:

Figure?1.?Logger Output Hierarchy

3.2.?Appenderhttp://jakarta.apache.org/log4j/docs/api/index.html):

A logger will only output messages that are of a level greater than or equal to it. If the level of a logger is not set it will inherit the level of the closest ancestor. So if a logger is created in the package com.foo.bar and no level is set for it, it will inherit the level of the logger created in com.foo. If no logger was created in com.foo, the logger created in com.foo.bar will inherit the level of the root logger, the root logger is always instantiated and available, the root logger is assigned the level DEBUG.

There are a number of ways to create a logger, one can retrieve the root logger:

Logger logger = Logger.getRootLogger();

One can create a new logger:

Logger logger = Logger.getLogger("MyLogger");

More usually, one instantiates a static logger globally, based on the name of the class:

static Logger logger = Logger.getLogger(test.class);

All these create a logger called "logger", one can set the level with:

logger.setLevel((Level)Level.WARN);

You can use any of 7 levels; Level.DEBUG, Level.INFO, Level.WARN, Level.ERROR, Level.FATAL, Level.ALL and Level.OFF.

ConsoleAppender appender = new ConsoleAppender(new PatternLayout());

          FileAppender appender = null;
          try {
             appender = new FileAppender(new PatternLayout(),"filename");
          } catch(Exception e) {}
        

FileAppender(Layout layout, String filename) 
          Instantiate a FileAppender and open the file designated by filename.
        

FileAppender(Layout layout, String filename, boolean append) 
          Instantiate a FileAppender and open the file designated by filename. 
        

          WriterAppender appender = null;
          try {
            appender = new WriterAppender(new PatternLayout(),new FileOutputStream("filename"));
          } catch(Exception e) {}
        

import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import org.apache.log4j.SimpleLayout;
import org.apache.log4j.FileAppender;
public class simpandfile {
   static Logger logger = Logger.getLogger(simpandfile.class);
   public static void main(String args[]) {
      SimpleLayout layout = new SimpleLayout();

      FileAppender appender = null;
      try {
         appender = new FileAppender(layout,"output1.txt",false);
      } catch(Exception e) {}

      logger.addAppender(appender);
      logger.setLevel((Level) Level.DEBUG);

      logger.debug("Here is some DEBUG");
      logger.info("Here is some INFO");
      logger.warn("Here is some WARN");
      logger.error("Here is some ERROR");
      logger.fatal("Here is some FATAL");
   }
}
        

import java.io.*;
import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import org.apache.log4j.HTMLLayout;
import org.apache.log4j.WriterAppender;
public class htmlandwrite {
   static Logger logger = Logger.getLogger(htmlandwrite.class);
   public static void main(String args[]) {
      HTMLLayout layout = new HTMLLayout();

      WriterAppender appender = null;
      try {
         FileOutputStream output = new FileOutputStream("output2.html");
         appender = new WriterAppender(layout,output);
      } catch(Exception e) {}

      logger.addAppender(appender);
      logger.setLevel((Level) Level.DEBUG);

      logger.debug("Here is some DEBUG");
      logger.info("Here is some INFO");
      logger.warn("Here is some WARN");
      logger.error("Here is some ERROR");
      logger.fatal("Here is some FATAL");
   }
}
        

import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import org.apache.log4j.PatternLayout;
import org.apache.log4j.ConsoleAppender;
public class consandpatt {
   static Logger logger = Logger.getLogger(consandpatt.class);
   public static void main(String args[]) {

      // Note, %n is newline
      String pattern =  "Milliseconds since program start: %r %n";
             pattern += "Classname of caller: %C %n";
             pattern += "Date in ISO8601 format: %d{ISO8601} %n";
             pattern += "Location of log event: %l %n";
             pattern += "Message: %m %n %n"; 
      
      PatternLayout layout = new PatternLayout(pattern);
      ConsoleAppender appender = new ConsoleAppender(layout);

      logger.addAppender(appender);
      logger.setLevel((Level) Level.DEBUG);

      logger.debug("Here is some DEBUG");
      logger.info("Here is some INFO");
      logger.warn("Here is some WARN");
      logger.error("Here is some ERROR");
      logger.fatal("Here is some FATAL");
   }
}
        

Log4j is usually used in conjunction with external configuration files so that options do not have to be hard-coded within the software. The advantage of using an external configuration file is that changes can be made to the options without having to recompile the software. A disadvantage could be, that due to the io instructions used, it is slightly slower.

There are two ways in which one can specify the external configuration file: a plain text file or an XML file. Since everything is written in XML these days, this tutorial will focus on the XML approach but will also include relevant plain text examples. To begin with, examine the sample XML config file shown below:

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

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
        
  <appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.SimpleLayout"/>
  </appender>

  <root>
    <priority value ="debug" />
    <appender-ref ref="ConsoleAppender"/>
  </root>

</log4j:configuration> 
    

The file starts with a standard XML declaration followed by a DOCTYPE declaration which indicates the DTD(Document Type Definition), this defines the structure of the XML file, what elements may be nested within other elements etc. This file is provided in the log4j distribution under src/java/org/apache/log4j/xml. Next comes the all-encapsulating log4j:configuration element, which was specified as the root element in the DOCTYPE declaration. Nested within the root element are two structures:

  <appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.SimpleLayout"/>
  </appender>      
    

Here an Appender is created and called "ConsoleAppender", note that any name could have been chosen, it is because of the contrivity of examples that this name was chosen. The class for the appender is then specified in full, when referring to classes, one always uses the fully qualified class name. An Appender must always have a name and a class specified. Nested within Appender is the layout element which defines the layout to be a SimpleLayout. Layout must always have the class attribute.

  <root>
    <priority value ="debug" />
    <appender-ref ref="ConsoleAppender"/>
  </root>      
    

The root element always exists and cannot be sub-classed. The example shows the priority being set to "debug" and the appender setup by including an appender-ref element, of which, more that one may be specified. See the file src/java/org/apache/log4j/xml/log4j.dtd in your log4j distribution for more information about the structure of an XML configuration file. The configuration file is pulled into the Java program like this:

DOMConfigurator.configure("configurationfile.xml");
    

The DOMConfigurator is used to initialise the log4j environment using a DOM tree. Here is the example xml configuration file:

import org.apache.log4j.Logger;
import org.apache.log4j.xml.DOMConfigurator;
public class externalxmltest {
   static Logger logger = Logger.getLogger(externalxmltest.class);
   public static void main(String args[]) {
      DOMConfigurator.configure("xmllog4jconfig.xml");
      logger.debug("Here is some DEBUG");
      logger.info("Here is some INFO");
      logger.warn("Here is some WARN");
      logger.error("Here is some ERROR");
      logger.fatal("Here is some FATAL");
   }
}
    

Here is an XML configuration file for a Logger implementing a FileAppender using a PatternLayout:

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

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
        
  <appender name="appender" class="org.apache.log4j.FileAppender">
    <param name="File" value="Indentify-Log.txt"/>
    <param name="Append" value="false"/>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d [%t] %p - %m%n"/>
    </layout>
  </appender>

  <root>
    <priority value ="debug"/>
    <appender-ref ref="appender"/>
  </root>

</log4j:configuration>
    

You can download this example from here: xmllog4jconfig2.xml. For more examples of using xml files to configure a log4j environment, see the src/java/org/apache/log4j/xml/examples/ directory in the log4j distribution.

Here is the configuration file discussed above, expressed in the form of a plain text file:

# initialise root logger with level DEBUG and call it BLAH
log4j.rootLogger=DEBUG, BLAH
# add a ConsoleAppender to the logger BLAH
log4j.appender.BLAH=org.apache.log4j.ConsoleAppender
# set set that layout to be SimpleLayout
log4j.appender.BLAH.layout=org.apache.log4j.SimpleLayout
    

You can download it here: plainlog4jconfig.txt. Here is a program implementing this:

import org.apache.log4j.Logger;
import org.apache.log4j.PropertyConfigurator;
public class externalplaintest {
   static Logger logger = Logger.getLogger(externalplaintest.class);
   public static void main(String args[]) {
      PropertyConfigurator.configure("plainlog4jconfig.xml");
      logger.debug("Here is some DEBUG");
      logger.info("Here is some INFO");
      logger.warn("Here is some WARN");
      logger.error("Here is some ERROR");
      logger.fatal("Here is some FATAL");
   }
}
    

You can download an example program that uses this configuration file here: files/externalplaintest.java. For more examples of using plain text files to configure a log4j environment, see the examples directory in the log4j distribution.

The use of external example files has only been briefly discussed here, it is assumed that you have the capacity to learn more by yourself by studying the examples provided with the log4j distribution and experimenting.