关于log4j

Index

1. Log4j的类图
2. Logger：日志写出器
   1. Logger的输出方法
   2. Logger的命名规则
   3. Log level
   4. 示例代码
   5. 关于logger的两点说明
3. Appender：日志目的地
   1. ConsoleAppender
   2. FileAppender
   3. RollingFileAppender
4. Layout：日志格式化器
   1. PatternLayout
   2. patterns in PatternLayout
5. Configuration：配置
   1. 默认的log4j初始化过程
   2. BasicConfigurator.configure()
   3. XML格式的log4j配置文件概述
   4. 在xml文件中配置appender和layout
   5. 我自己的一个使用xml文件配置log4j环境的很简单的例子
6. Log4j的编码习惯
7. 参考资料

Log4j的类图

1. Logger - 日志写出器，供程序员输出日志信息
2. Appender - 日志目的地，把格式化好的日志信息输出到指定的地方去
   1. ConsoleAppender - 目的地为控制台的Appender
   2. FileAppender - 目的地为文件的Appender
   3. RollingFileAppender - 目的地为大小受限的文件的Appender
3. Layout - 日志格式化器，用来把程序员的logging request格式化成字符串
   1. PatternLayout - 用指定的pattern格式化logging request的Layout

Logger：日志写出器

Logger对象是用来取代System.out或者System.err的日志写出器，用来供程序员输出日志信息。

Logger的输出方法

Logger类对象提供一系列方法供程序员输出日志信息。

        

        ------ Log4j APIs : class Logger ------
        
        
        
        // Printing methods :
        
        public void debug(Object msg);
        public void debug(Object msg, Throwable t);
        
        public void info(Object msg);
        public void info(Object msg, Throwable t);
        
        public void warn(Object msg);
        public void warn(Object msg, Throwable t);
        
        public void error(Object msg);
        public void error(Object msg, Throwable t);
        
        public void fatal(Object msg);
        public void fatal(Object msg, Throwable t);
        
        // Generic printing method :
        
        public void log(Level l, Object msg);
      

Logger的命名规则

Logger由一个String类的名字识别，logger的名字是大小写敏感的，且名字之间具有继承的关系，子名有父名作为前缀，用点号.分隔。如：x.y是x.y.z的父亲。

根logger (root logger)是所有logger的祖先，它具有如下属性：1) 它总是存在的；2) 它不可以通过名字获得。

通过调用public static Logger Logger.getRootLogger()获得root logger；通过调用public static Logger Logger.getLogger(String name)或者public static Logger Logger.getLogger(Class clazz)获得（或者创建）一个named logger。后者相当于调用Logger.getLogger(clazz.getName())。

在某对象中，用该对象所属的类为参数，调用Logger.getLogger(Class clazz)以获得logger被认为是目前所知的最理智的命名logger的方法。

Log level

每个logger都被分配了一个日志级别 (log level)，用来控制日志信息的输出。未被分配level的logger将继承它最近的父logger的level。

每条输出到logger的日志请求(logging request)也都有一个level，如果该request的level大于等于该logger的level，则该request将被处理（称为enabled）；否则该request将被忽略。故可得知：

1. logger的level越低，表示该logger越详细
2. logging request的level越高，表示该logging request越优先输出

Level类中预定义了五个level，它们的大小关系如下：

        Level.ALL < Level.DEBUG < Level.INFO < Level.WARN < Level.ERROR < Level.FATAL < Level.OFF
      

示例代码

以下代码将用自己所属的类为参数，创建一个logger，启用默认配置，设置其level并向其输出若干logging request。

import org.apache.log4j.Logger;
import org.apache.log4j.BasicConfigurator;
import org.apache.log4j.Level;
public class Log4jTest {
    public static void main(String argv[]) {
    
        
        // Create a logger by the name of class Log4jTest.
        
        Logger logger = Logger.getLogger(Log4jTest.class);
        
        // Use the default configuration.
        
        BasicConfigurator.configure();
        
        // Set the logger level to Level.INFO
        
        logger.setLevel(Level.INFO);
        
        // This request will be disabled since Level.DEBUG < Level.INFO.
                  
        logger.debug("This is debug.");
        
        // These requests will be enabled.
                  
        logger.info("This is an info.");
        logger.warn("This is a warning.");
        logger.error("This is an error.");
        logger.fatal("This is a fatal error.");
        
        return;
    }
}
      

关于logger的两点说明

1. 用同名参数调用Logger.getLogger(String name)将返回同一个logger的引用。故可以在一个地方配置logger，在另外一个地方获得配置好的logger，而无须相互间传递logger的引用。
2. logger的创建可以按照任意的顺序，即，父logger可以后于子logger被创建。log4j将自动维护logger的继承树。

Appender：日志目的地

每个logger都可以拥有一个或者多个appender，每个appender表示一个日志的输出目的地，比如console或者某个文件。可以使用Logger.addAppender(Appender app)为logger增加一个appender；可以使用Logger.removeAppender(Appender app)为logger移除一个appender。

默认情况下，logger的additive标志被设置为true，表示子logger将继承父logger的所有appenders。该选项可以被重新设置，表示子logger将不再继承父logger的appenders。

root logger拥有目标为system.out的consoleAppender，故默认情况下，所有的logger都将继承该appender。

      

      ------ Log4j APIs : class Logger ------
      
      
      
      // 为logger对象增加或者移除一个Appender对象 :.
      
      public void appAppender(Appender app);
      public void removeAppender(Appender app);
      
      // 获得和设置additive标志：是否继承父logger的appenders :.
      // 注意：在设置additive标志为false时，必须保证已经为该logger设置了新的appender， :.
      // 否则log4j将报错：log4j:WARN No appenders could be found for logger (x.y.z). :.
      
      public boolean getAdditivity();
      public void setAdditivity(boolean additive);
    

ConsoleAppender

可以使用ConsoleAppender对象把日志输出到控制台。每个ConsoleAppender都有一个target，表示它的输出目的地。它可以是System.out，标准输出设备（缓冲显示屏）；或者是System.err，标准错误设备（不缓冲显示屏）。ConsoleAppender的使用方法参考如下API :.

        

        ------ Log4j APIs : class ConsoleAppender extends WriterAppender ------
        
      
        
        // 构造方法，使用一个Layout对象构造一个ConsoleAppender对象 :.
        // 默认情况下，ConsoleAppender的target是System.out :.
        
        public ConsoleAppender(Layout layout);
        
        // 构造方法，使用一个Layout对象和一个target字符串构造ConsoleAppender对象 :.
        // target的可能取值为ConsoleAppender.SYSTEM_OUT和ConsoleAppender.SYSTEM_ERR :.
        
        public ConsoleAppender(Layout layout, String target);
      

FileAppender

可以使用FileAppender对象把日志输出到一个指定的日志文件中去。使用方法可以参考如下的API :.

        

        ------ Log4j APIs : class FileAppender extends WriterAppender ------
        
      
        
        // 构造方法，使用一个Layout对象和日志文件名构造一个FileAppender对象 :.
        
        public FileAppender(Layout layout, String filename)
            throws IOException;
        public FileAppender(Layout layout, String filename, boolean append)
            throws IOException;
      

RollingFileAppender

可以使用FileAppender的子类RollingFileAppender对象，把日志输出到一个指定的日志文件中。不同的是该日志文件的大小受到限制，当日志内容超出最大的尺寸时，该文件将向上滚动（最老的日志被擦除）。还可以在该类对象中指定为日志文件做多少个备份。具体使用方法参考如下API :.

        

        ------ Log4j APIs : class RollingFileAppender extends FileAppender ------
        
      
        
        // 构造方法，使用一个Layout对象和日志文件名构造一个RollingFileAppender对象 :.
        
        public RollingFileAppender(Layout layout, String filename)
            throws IOException;
        public RollingFileAppender(Layout layout, String filename, boolean append)
            throws IOException;
        
        // 获得和设置日志备份文件的个数 :.
        
        public int getMaxBackupIndex();
        public void setMaxBackupIndex(int index);
        
        // 获得和设置滚动日志文件的最大尺寸 :.
        
        public long getMaximumFileSize();
        public void setMaximumFileSize(long size);
      

Layout：日志格式化器

每个appender都和一个layout相联系；layout的任务是格式化用户的logging request，appender的任务是把layout格式化好的输出内容送往指定的目的地。

PatternLayout

PatternLayout是Layout的一个子类，用来使用类似C语言的printf函数中使用的格式控制字符串来控制日志的输出格式。使用方法参考如下API :.

        

        ------ Log4j APIs : class PatternLayout extends Layout ------
        
      
        
        // 无参数构造方法，使用DEFAULT_CONVERSION_PATTERN构造一个PatternLayout :.
        // 注意：DEFAULT_CONVERSION_PATTERN为"%m%n"，只打印消息信息 :.
        
        public PatternLayout();
        
        // 构造方法，使用自定义的pattern构造一个PatternLayout :.
        
        public PatternLayout(String pattern);
        
        // 获得和设置PatternLayout对象的日志pattern :.
        
        public String getConversionPattern();
        public void setConversionPattern(String pattern);
      

Configuration：配置

对log4j环境的配置就是对root logger的配置，包括把root logger设置为哪个级别(level)；为它增加哪些appender，等等。这些可以通过设置系统属性的方法来隐式地完成，也可以在程序里调用XXXConfigurator.configure()方法来显式地完成。

默认的log4j初始化过程

Logger类的静态初始化块(static initialization block)中对log4j的环境做默认的初始化。注意：如果程序员已经通过设置系统属性的方法来配置了log4j环境，则不需要再显式地调用XXXConfigurator.configure()方法来配置log4j环境了。

Logger的静态初始化块在完成初始化过程时将检查一系列log4j定义的系统属性。它所做的事情如下：

1. 检查系统属性log4j.defaultInitOverride，如果该属性被设置为false，则执行初始化；否则（只要不是false，无论是什么值，甚至没有值，都是否则），跳过初始化。
2. 把系统属性log4j.configuration的值赋给变量resource。如果该系统变量没有被定义，则把resource赋值为"log4j.properties"。注意：在apache的log4j文档中建议使用定义log4j.configuration系统属性的方法来设置默认的初始化文件是一个好方法。
3. 试图把resource变量转化成为一个URL对象url。如果一般的转化方法行不通，就调用org.apache.log4j.helpers.Loader.getResource(resource, Logger.class)方法来完成转化。
4. 如果url以".html"结尾，则调用方法DOMConfigurator.configure(url)来完成初始化；否则，则调用方法PropertyConfigurator.configure(url)来完成初始化。如果url指定的资源不能被获得，则跳出初始化过程。

BasicConfigurator.configure()

BasicConfigurator.configure()方法使用最简的方法配置log4j环境。注：所谓配置log4j环境，就是指配置root logger，因为所有其它的logger都是root logger的后代，所以它们（默认情况下）都将继承root logger的性质。

BasicConfigurator.configure()完成的任务是：

1. 用默认pattern创建PatternLayout对象p：
   PatternLayout p = new PatternLayout("%-4r[%t]%-5p%c%x - %m%n");
2. 用p创建ConsoleAppender对象a，目标是system.out，标准输出设备：
   ConsoleAppender a = new ConsoleAppender(p,ConsoleAppender.SYSTEM_OUT);
3. 为root logger增加一个ConsoleAppender p：
   rootLogger.addAppender(p);
4. 把root logger的log level设置为DEBUG级别：
   rootLogger.setLevel(Level.DEBUG);

xml格式的log4j配置文件概述

xml格式的log4j配置文件需要使用org.apache.log4j.html.DOMConfigurator.configure()方法来读入。对xml文件的语法定义可以在log4j的发布包中找到：org/apache/log4j/xml/log4j.dtd。

log4j的xml配置文件的树状结构

log4j的xml配置文件的树状结构如下所示，注意下图只显示了常用的部分。 :.

          xml declaration and dtd
            |
          log4j:configuration
            |
            +-- appender (name, class)
            |     |
            |     +-- param (name, value)
            |     +-- layout (class)
            |           |
            |           +-- param (name, value)
            +-- logger (name, additivity)
            |     |
            |     +-- level (class, value)
            |     |     |
            |     |     +-- param (name, value)
            |     +-- appender-ref (ref)
            +-- root
                  |
                  +-- param (name, class)
                  +-- level
                  |     |
                  |     +-- param (name, value)
                  +-- appender-ref (ref)  
        

xml declaration and dtd

xml配置文件的头部包括两个部分：xml声明和dtd声明。头部的格式如下： :.

log4j:configuration (root element)

1. xmlns:log4j [#FIXED attribute] : 定义log4j的名字空间，取定值""
2. appender [* child] : 一个appender子元素定义一个日志输出目的地
3. logger [* child] : 一个logger子元素定义一个日志写出器
4. root [? child] : root子元素定义了root logger

appender

appender元素定义一个日志输出目的地。

1. name [#REQUIRED attribute] : 定义appender的名字，以便被后文引用
2. class [#REQUIRED attribute] : 定义appender对象所属的类的全名
3. param [* child] : 创建appender对象时传递给类构造方法的参数
4. layout [? child] : 该appender使用的layout对象

layout

layout元素定义与某一个appender相联系的日志格式化器。

1. class [#REQUIRED attribute] : 定义layout对象所属的类的全名
2. param [* child] : 创建layout对象时传递给类构造方法的参数

logger

logger元素定义一个日志输出器。

1. name [#REQUIRED attribute] : 定义logger的名字，以便被后文引用
2. additivity [#ENUM attribute] : 取值为"true"（默认）或者"false"，是否继承父logger的属性
3. level [? child] : 定义该logger的日志级别
4. appender-ref [* child] : 定义该logger的输出目的地

root

root元素定义根日志输出器root logger。

1. param [* child] : 创建root logger对象时传递给类构造方法的参数
2. level [? child] : 定义root logger的日志级别
3. appender-ref [* child] : 定义root logger的输出目的地

level

level元素定义logger对象的日志级别。

1. class [#IMPLIED attribute] : 定义level对象所属的类，默认情况下是"org.apache.log4j.Level类
2. value [#REQUIRED attribute] : 为level对象赋值。可能的取值从小到大依次为"all"、"debug"、"info"、"warn"、"error"、"fatal"和"off"。当值为"off"时表示没有任何日志信息被输出
3. param [* child] : 创建level对象时传递给类构造方法的参数

appender-ref

appender-ref元素引用一个appender元素的名字，为logger对象增加一个appender。

1. ref [#REQUIRED attribute] : 一个appender元素的名字的引用
2. appender-ref元素没有子元素

param

param元素在创建对象时为类的构造方法提供参数。它可以成为appender、layout、filter、errorHandler、level、categoryFactory和root等元素的子元素。

1. name and value [#REQUIRED attributes] : 提供参数的一组名值对
2. param元素没有子元素

在xml文件中配置appender和layout

创建不同的Appender对象或者不同的Layout对象要调用不同的构造方法。可以使用param子元素来设定不同的参数值。

创建ConsoleAppender对象

ConsoleAppender的构造方法不接受其它的参数。 :.

          ... ... ... ...
          
            
              ... ...
            
          
          ... ... ... ...
        

创建FileAppender对象

可以为FileAppender类的构造方法传递两个参数：File表示日志文件名；Append表示如文件已存在，是否把日志追加到文件尾部，可能取值为"true"和"false"（默认）。 :.

          ... ... ... ...
          
            
            
            
              ... ...
            
          
          ... ... ... ...
        

创建RollingFileAppender对象

除了File和Append以外，还可以为RollingFileAppender类的构造方法传递两个参数：MaxBackupIndex备份日志文件的个数（默认是1个）；MaxFileSize表示日志文件允许的最大字节数（默认是10M）。 :.

          ... ... ... ...
          
            
            
            
            
            
              ... ...
            
          
          ... ... ... ...
        

创建PatternLayout对象

可以为PatternLayout类的构造方法传递参数ConversionPattern。 :.

          ... ... ... ...
          
          
          ... ... ... ...
        

我自己的一个使用xml文件配置log4j环境的很简单的例子

为WSOTA项目开发Java Web start的胖客户端时，使用了如下的xml文件配置log4j环境（文件名为wsota-rc.log4j.html）：:.

在胖客户程序中使用了如下代码来使用外部xml文件配置log4j环境，注意该代码段位于程序的main class的静态初始化块中，含有以下代码的类和xml配置文件在同一个目录下：:.

  import org.apache.log4j.html.DOMConfigurator;
  
  public class SAPFrame extends JFrame {
      static {
          DOMConfigurator.configure(SapFrame.class.getResource("wsota-rc.log4j.html"));
      }
      ... ... ... ...
  }
      

Log4j的编码习惯

1. 让每个类都拥有一个private static的Logger对象，用来输出该类中的全部日志信息
2. 使用xml文件来完成对log4j环境的配置。在项目的main class中的静态初始化块里放log4j环境的配置代码。注意：在一个项目中，log4j环境只需要被配置一次，而不是在每个使用了logger的类里都需要调用一次
3. 用MyClass.class作为参数创建该类的静态Logger对象
4. 补充中...

参考资料

1. Log4j主页上的相关文档：
2. Ashley J.S Mills的log4j教程：http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/log4j/log4j.html