== Introduction ==

[http://logging.apache.org/log4j/docs/ Log4J] is a logging framework developed as part of the Jakarta project and distributed under the Apache Sowtware Licens. The Log4J framework gives you a fully configurable logging environment for your applications. It can easily be configured through code in your program or using configuration files.

The basic architecture of Log4J consists of 3 main components:
* loggers: Recives logging events from the application and directs them to one or more appenders. Loggers can be assigned the levels ALL, DEBUG, INFO, WARN, ERROR, FATAL, or OFF to control which messages should be handled or not.
* appenders: Handels logging events from the loggers and writes them to a destination. There are pre-written appenders for writing to console, logfiles (even daily rotating once), UNIX syslog, NT Eventlog and many many more. There are even appenders to send log messages by email (and as IM messages using Jabber).
* layout: Is called by the appenders to format the message before output. Using layout components the log message can be formated to contain every thing from the acctual message to the very file and line the message was printed on. This also includes process/thread name and ofcourse date and time.

== Using ==
=== Qiuck start ===
Using Log4J in your application is simple. Create a logger with a given name and then use that logger in your application to print messages.

 // Import log4j classes.
 import org.apache.log4j.Logger;
 public class MyLoggerApp {
   // Define a static logger variable so that it references the
   // Logger instance named "MyLoggerApp"
   static private Logger logger = Logger.getLogger("MyLoggerApp");
   public static void main(String[] args) {
     logger.info("starting main.");
     logger.debug("This is a debug message");
     logger.info("This is a info message");
     logger.warn("This is a warning message");
     logger.error("This is a error message");
     logger.fatal("This is a fatal message");

=== Loggers ===
A logger is the component used in your program to generate log events. Loggers are created using the 'Logger' factory class. All loggers have a name which can be used to build a logger hierarchy. Each level of this hierarchy is seperated with a dot ('.') similar to the way one defines packages and classes in Java. Loggers inherits properties from its parents when it comes to logging level and other configuration data. Below is a example of a program using two diffrent loggers to log diffrent aspects of the application.

  // Import log4j classes.
 import org.apache.log4j.Logger;
 public class TwoLoggerApp {
   // Define two logger variables
   static private Logger l1 = Logger.getLogger("TwoLoggerApp.main");
   static private Logger l2 = Logger.getLogger("TwoLoggerApp.security");
   public static void main(String[] args) {
     if ( args.length < 2 ) {
        l1.error("program invoked with not enough arguments");
     if ( verifyUser(args[0], args[1]) ) {
       l1.debug("This is a debug message");
       l1.info("This is a info message");
       l1.warn("This is a warning message");
       l1.error("This is a error message");
       l1.fatal("This is a fatal message");
   private static bool verifyUser(String username, String password) {
      if ( username.equals("joe") && password.equals("secret") ) {
        l2.info("User "+username+ " successfully logged in");   
        return true;
      else {
        l2.warn("Error logging in for user " + username);
        return false;

You can now in the configuration file setup both these loggers to log to the same appender using the name of there ancestor logger "TwoLoggerApp".

== Configure ==
Configuring what the loggers should do with the events generated in the code we have to configure the Log4J framework. This can be done using the Log4J configuration API. But the easiest way to configure Log4J is to use properties file. Log4J can be configured using both Java-properties (key-value syntax) and XML formated files. By default Log4J first searches for properties file called log4j.xml and then for a file called log4j.properties.

The XML formated file is more flexible and can support a wider range of function (such as filters) than the properties file format.

=== Properties ===
Below is a simple example of a properties style log4j property file for logging all messages (DEBUG or higher) to the console. Every thing after a '#'-sign are considered to be a comment.
The file must always have a configuration for the rootLogger. This is the default logger from which all other loggers defined in your program inherits.

  log4j.rootLogger=DEBUG, A1
  # A1 is set to be a ConsoleAppender.
  # A1 uses PatternLayout.
  log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c %x - %m%n

=== XML ===
Below is a simple XML formated Log4J property file.

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

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">

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

<appender name="A1" class="org.apache.log4j.ConsoleAppender">
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d [%t] %-5p %c %x - %m%n"/>


== Appenders ==
=== ConsoleAppender ===
This appender prints the formated message to the console.

=== FileAppender ===
This appender prints the formated message to a file.

=== DailyRollingFileAppender ===
This appender prints the formated message to a file which is rotated on a daily (or other time unit) basis.

=== IMAppender ===
[http://www-106.ibm.com/developerworks/java/library/j-instlog/ IM_Appender] is a Log4J appender for sending logging events to a instant messanger client using the Jabber protocoll.