View source for Log4J

[[Category:Logging Frameworks (Java)]]
==Configuration==
===Using Configuration Text File===
-Sample config text file

 # Set root category priority to DEBUG and set its only appender to A1
 log4j.rootCategory=DEBUG, A1
 
 # A1 is set to be a ConsoleAppender (writes to system console).
 log4j.appender.A1=org.apache.log4j.ConsoleAppender
 
 # A1 uses PatternLayout.
 log4j.appender.A1.layout=org.apache.log4j.PatternLayout
 #log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
 #log4j.appender.A1.layout.ConversionPattern=%5p [%t] (%F:%L) - %m%n
 log4j.appender.A1.layout.ConversionPattern=%n%x%n%d{yyyy-MM-dd HH:mm:ss} [%-5p] %C.%M(%F:%L) %n%m%n%n


=== Using configuration XML file ===
-Sample config xml file: <code>log4j.xml</code>
<source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
 
 <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
    
     <appender name="normal" class="org.apache.log4j.ConsoleAppender">
         <param name="Threshold" value="DEBUG"/>
         <layout class="org.apache.log4j.PatternLayout">
             <param name="ConversionPattern" value="///=========%n%x%n%d{yyyy-MM-dd HH:mm:ss} [%-5p] %C.%M(%F:%L) %n%m%n=========///%n"/>
         </layout>
     </appender>

     <appender name="EMAIL" class="org.apache.log4j.net.SMTPAppender">
         <param name="BufferSize" value="512" />
         <param name="SMTPHost" value="email.server.com" />
         <param name="From" value="System Admin &lt;admin@yoursite.com&gt;" />
         <param name="To" value="developer@developers.email.com" />
         <param name="Subject" value="[System:Error] Application Error Message" />
         <layout class="org.apache.log4j.PatternLayout">
             <param name="ConversionPattern" value="%n%x%n%d{yyyy-MM-dd HH:mm:ss} [%-5p] %C.%M(%F:%L) %n%m%n" />
         </layout>
         <filter class="org.apache.log4j.varia.LevelRangeFilter">
             <param name="LevelMin" value="ERROR"/>
             <param name="LevelMax" value="FATAL"/>
             <param name="AcceptOnMatch" value="true"/>
         </filter>
     </appender>
     
     <logger name="net.kevin" additivity="false">
         <level value="DEBUG"/>
         <appender-ref ref="normal"/>
         <appender-ref ref="EMAIL"/>
     </logger>
     
    <root>
         <level value="INFO"/>
         <appender-ref ref="normal"/>
     </root>
     
     <!--
     1. Use debug to write debugging messages which should not be printed when the application is in production.
     2. Use info for messages similar to the "verbose" mode of many applications.
     3. Use warn for warning messages which are logged to some log but the application is able to carry on without a problem.
     4. Use error for application error messages which are also logged to some log but, still, the application can hobble along.
     Such as when some administrator-supplied configuration parameter is incorrect and you fall back to using
     some hard-coded default value.
     5. Use fatal for critical messages, after logging of which the application quits abnormally.
     -->
     
     <!--
     <logger name="org.apache" additivity="false">
     <level value="INFO"/>
     <appender-ref ref="normal"/>
     </logger>
     
     <root>
     <level value="WARN"/>
     <appender-ref ref="normal"/>
     </root>
     -->
 </log4j:configuration>
</source>


-Conversion characters:
* %m: Outputs your message.
* %p: Outputs the priority of the logging event.
* %r: Outputs the number of milliseconds elapsed since the start of the application until the creation of the logging event.
* %c: Outputs the category of the logging event. Example: For the category name "a.b.c", the pattern %c{2} will output "b.c". {2} means "output last two components of the dot-separated category name". If no {n} is there, full Category name is output by default.
* %t: Outputs the name of the thread that generated the logging event.
* %x: Outputs the nested diagnostic context (NDC) associated with the thread that generated the logging event. Useful when multiple clients are handled by separate threads such as in Java servlets.
* %n: Outputs the platform-dependent newline character(s). Preferable to specifying "\n" or "\r\n" etc.
* %%: Outputs a single percent sign.
* WARNING: The patterns below will slow down the execution of your program somewhat. Avoid unless execution speed is not an issue.
* %d: Outputs the date of the logging event. The date conversion specifier may be followed by a date format specifier enclosed between braces. Example: %d{HH:mm:ss,SSS} or %d{dd MMM yyyy HH:mm:ss,SSS}. If no date format specifier is given then ISO8601 format is assumed. The date format specifier admits the same syntax as the time pattern string of Java's SimpleDateFormat which is slow. For faster performance, use %d{ISO8601}, %d{ABSOLUTE}, %d{RELATIVE} (millisecs since program start, fastest) or %d{DATE} which use log4j's ISO8601DateFormat, AbsoluteTimeDateFormat, RelativeTimeDateFormat and DateTimeDateFormat date formatters respectively.
* %l: Outputs source code location information. Shortcut for %C.%M(%F:%L).
* %C: Outputs the fully-qualified class name of the caller issuing the logging request. Example: For the class name "org.apache.xyz.SomeClass", the pattern %C{1} will output "SomeClass". {1} means "output last one component of the fully-qualified class name". If no {n} is there, full class name is output by default.
* %M: Outputs the method name where the logging request was issued.
* %F: Outputs the file name where the logging request was issued.
* %L: Outputs the line number from where the logging request was issued. 


=== Filter Log By Levels ===
If a log must be made in different ways depending on the level of it, there are two ways to do it.
# Using LevelMatchFilter and DenyAllFilter
# LevelRangeFilter

==== <code>LevelMatchFilter</code> and <code>DenyAllFilter</code> ====
If the log should be filtered by exact level, LevelMatchFilter and DenyAllFilter can be used.
-To use it, put these filter elements as the child nodes of the appender element by which the log is meant to be handled.

 <filter class="org.apache.log4j.varia.LevelMatchFilter">
     <param name="LevelToMatch" value="INFO" />
     <param name="AcceptOnMatch" value="true"/>
 </filter>
 <filter class="org.apache.log4j.varia.DenyAllFilter" />

-Example
<source lang="xml">
 <appender name="only-info" class="org.apache.log4j.FileAppender"> 
     <param name="File" value="only-info.log"/> 
     <layout class="org.apache.log4j.PatternLayout"> 
         <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss} [%-5p] %C.%M(%F:%L) %n%m%n%n"/> 
     </layout> 
     <filter class="org.apache.log4j.varia.LevelMatchFilter">
         <param name="LevelToMatch" value="INFO" />
         <param name="AcceptOnMatch" value="true"/>
     </filter>
     <filter class="org.apache.log4j.varia.DenyAllFilter" />
 </appender>
</source>
-With this setup, all the log events other than <code>info</code> will be ignored by this appender. So the <code>only-info.log</code> file contains the log with <code>info</code> level.


==== <code>LevelRangeFilter</code> ====
If the range of log must be handled by a specific appender, LevelRangeFilter can be used.
-Put LevelRangeFilter element as the child node of the appender element by which the logs must be handled.

 <filter class="org.apache.log4j.varia.LevelRangeFilter">
     <param name="LevelMin" value="ERROR"/>
     <param name="LevelMax" value="FATAL"/>
     <param name="AcceptOnMatch" value="true"/>
 </filter>

-Example
<source lang="xml">
 <appender name="only-info" class="org.apache.log4j.FileAppender"> 
     <param name="File" value="error-fatal.log"/> 
     <layout class="org.apache.log4j.PatternLayout"> 
         <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss} [%-5p] %C.%M(%F:%L) %n%m%n%n"/> 
     </layout> 
     <filter class="org.apache.log4j.varia.LevelRangeFilter">
         <param name="LevelMin" value="ERROR"/>
         <param name="LevelMax" value="FATAL"/>
         <param name="AcceptOnMatch" value="true"/>
     </filter>
 </appender>
</source>
-With this setup, all the error anf fatal logs are stored in the <code>error-fatal.log</code> file


==== Level Filtering for <code>SMTPAppender</code> ====
The level filtering with the above means does not work if the appender is <code>org.apache.log4j.net.SMTPAppender</code> and the level to filter is lower than <code>error</code> level. The <code>SMTPAppender</code> by default works only when the log event level is <code>error</code> or higher meaning <code>error</code> and <code>fatal</code>. To make it work with other levels than <code>error</code> and <code>fatal</code>, an <code>Evaluator</code> class has to be created and used. The <code>Evaluator</code> can be created by implementing <code>org.apache.log4j.spi.TriggeringEventEvaluator</code> interface. This interface has only one method which is <code>public boolean isTriggeringEvent(LoggingEvent event)</code>. So depending on the return value of this method in the concrete class which implements the interface, the SMTPAppender may work even if the log event level is neither <code>error</code> nor <code>fatal</code>.

-Example: here is an example of <code>Evaluator</code> which checks if the the log event is <code>warn</code>.

<source lang="java5">
/**
 * This is an Evaluator class for org.apache.log4j.net.SMTPAppender logging appender. By default,
 * org.apache.log4j.net.SMTPAppender does not send an email if the log level is less than error. This class is to
 * evaluate if the current logging event is warning. If it is, it returns true when invoking isTriggeringEvent() method.
 * 
 * @author Lee, SeongHyun (Kevin)
 * @version 1.0 (2009-03-18)
 */
package com.lckymn.kevin.log;

import org.apache.log4j.Level;
import org.apache.log4j.spi.LoggingEvent;
import org.apache.log4j.spi.TriggeringEventEvaluator;

/**
 * This is an Evaluator class for org.apache.log4j.net.SMTPAppender logging appender. By default,
 * org.apache.log4j.net.SMTPAppender does not send an email if the log level is less than error. This class is to
 * evaluate if the current logging event is warning. If it is, it returns true when invoking isTriggeringEvent() method.
 * 
 * The information of this Evaluator class must be set as the child element of an SMTPAppender appender element in the
 * log4j.xml file. <div> e.g.
 * 
 * <pre>
 * &lt;appender name=&quot;WARNING-EMAIL&quot;  class=&quot;org.apache.log4j.net.SMTPAppender&quot;&gt;
 *     &lt;param name=&quot;EvaluatorClass&quot; value=&quot;com.lckymn.kevin.log.OnlyWarningEvaluator&quot; /&gt;
 *     ...
 * &lt;/appender&gt;
 * </pre>
 * 
 * </div>
 * 
 * @author Lee, SeongHyun (Kevin)
 * @version 1.0 (2009-03-18)
 * 
 */
public final class OnlyWarningEvaluator implements TriggeringEventEvaluator
{
    /**
     * Check if the LoggingEvent is Level.WARN which is the trigger to send an email with a warning message through the
     * org.apache.log4j.net.SMTPAppender.
     * 
     * @param event 
     *            the LoggingEvent happened.
     * @return true if the LoggingEvent is Level.WARN. false otherwise.
     */
    public boolean isTriggeringEvent(LoggingEvent event)
    {
        return Level.WARN.getSyslogEquivalent() == event.getLevel().getSyslogEquivalent();
    }

}
</source>

-Then the information of thie evaluator has to be set in the <code>log4j.xml</code> file
 <param name="EvaluatorClass" value="com.lckymn.kevin.log.OnlyWarningEvaluator" />

-Example
<source lang="xml">
<appender name="WARNING-EMAIL"  class="org.apache.log4j.net.SMTPAppender">
    <param name="EvaluatorClass" value="com.lckymn.kevin.log.OnlyWarningEvaluator" />
    <param name="BufferSize" value="512" />
    <param name="SMTPHost" value="mail.email.server" />
    <param name="From" value="Admin &lt;admin@your.domain&gt;" />
    <param name="To" value="your.email@your.domain" />
    <param name="Subject" value="[Warning] Warning!!!" />
    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%n%x%n%d{yyyy-MM-dd HH:mm:ss} [%-5p] %C.%M(%F:%L) %n%m%n" />
    </layout>
    <filter class="org.apache.log4j.varia.LevelMatchFilter">
        <param name="LevelToMatch" value="WARN"/>
        <param name="AcceptOnMatch" value="true"/>
    </filter>
    <filter class="org.apache.log4j.varia.DenyAllFilter" />
</appender>
</source>



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

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
    
    <appender name="normal" class="org.apache.log4j.ConsoleAppender">
        <param name="Threshold" value="DEBUG"/>
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" 
            value="///=========%n%x%n%d{yyyy-MM-dd HH:mm:ss} [%-5p] %C.%M(%F:%L) %n%m%n=========///%n"/>
        </layout>
    </appender>

    <appender name="WARNING-EMAIL"  class="org.apache.log4j.net.SMTPAppender">
        <param name="EvaluatorClass" value="com.lckymn.kevin.log.OnlyWarningEvaluator" />
        <param name="BufferSize" value="512" />
        <param name="SMTPHost" value="mail.your.domain" />
        <param name="From" value="Admin &lt;admin@your.domain&gt;" />
        <param name="To" value="your.email@your.domain" />
        <param name="Subject" value="[YourApplication] Warning!!!" />
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%n%x%n%d{yyyy-MM-dd HH:mm:ss} [%-5p] %C.%M(%F:%L) %n%m%n" />
        </layout>
        <filter class="org.apache.log4j.varia.LevelMatchFilter">
            <param name="LevelToMatch" value="WARN"/>
            <param name="AcceptOnMatch" value="true"/>
        </filter>
        <filter class="org.apache.log4j.varia.DenyAllFilter" />
    </appender>
        
    <appender name="ERROR-EMAIL"  class="org.apache.log4j.net.SMTPAppender">
        <param name="BufferSize" value="512" />
        <param name="SMTPHost" value="mail.your.domain" />
        <param name="From" value="Admin &lt;admin@your.domain&gt;" />
        <param name="To" value="your.email@your.domain" />
        <param name="Subject" value="[YourApplication] Error!!!" />
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%n%x%n%d{yyyy-MM-dd HH:mm:ss} [%-5p] %C.%M(%F:%L) %n%m%n" />
        </layout>
        <filter class="org.apache.log4j.varia.LevelRangeFilter">
            <param name="LevelMin" value="ERROR"/>
            <param name="LevelMax" value="FATAL"/>
            <param name="AcceptOnMatch" value="true"/>
        </filter>
    </appender>

    <logger name="com.lckymn.kevin" additivity="false">
        <level value="DEBUG"/>
        <appender-ref ref="normal"/>
        <appender-ref ref="WARNING-EMAIL"/>
        <appender-ref ref="ERROR-EMAIL"/>
    </logger>
    
    <root>
        <level value="INFO"/>
        <appender-ref ref="normal"/>
    </root>
    
</log4j:configuration>
</source>
-With this setup file, any log event equals to or higher than <code>DEBUG</code> is displayed on the console.

-If it is <code>WARN</code>, it is displayed on the console, and an email notification is sent with the subject of '[YourApplication] Warning!!!'.

-If it is <code>ERROR</code> or <code>FATAL</code>, it is displayed on the console, and an email notification is sent with the subject of '[YourApplication] Error!!!'.


==References==
* http://logging.apache.org/log4j/1.2/publications.html

* http://www.vipan.com/htdocs/log4jhelp.html

* http://wiki.apache.org/logging-log4j/Log4jXmlFormat

* http://wiki.apache.org/logging-log4j/LogToAppenderByLevel

* http://wiki.apache.org/logging-log4j/SMTPAppender