LOG4J参考资料

LOG4J参考资料
 官网：http://logging.apache.org/log4j/
 第一部分，快速入门
 
   首先，需要去下载LOG4J这个软件并解压缩出其中的log4j.jar.在你的应用程序的classpath中包含该JAR文件，你也可以简单地将这个文件拷贝到JDK的%java_home%/lib/ext目录下。
   在作完以上工作后，你可以将下面的代码保存到名为TestLogging.java中：
 ##############################
 import org.apache.log4j.*;
 
 // How to use log4j
 public class TestLogging {
 
     // Initialize a logging category.  Here, we get THE ROOT CATEGORY
     //static Category cat = Category.getRoot();
     // Or, get a custom category
     static Category cat = Category.getInstance(TestLogging.class.getName());
 
     // From here on, log away!  Methods are: cat.debug(your_message_string),
     // cat.info(...), cat.warn(...), cat.error(...), cat.fatal(...)
 
     public static void main(String args[]) {
         // Try a few logging methods
         cat.debug("Start of main()");
         cat.info("Just testing a log message with priority set to INFO");
         cat.warn("Just testing a log message with priority set to WARN");
         cat.error("Just testing a log message with priority set to ERROR");
         cat.fatal("Just testing a log message with priority set to FATAL");
 
         // Alternate but INCONVENIENT form
         cat.log(Priority.DEBUG, "Calling init()");
 
         new TestLogging().init();
     }
 
     public void init() {
         java.util.Properties prop = System.getProperties();
         java.util.Enumeration enum = prop.propertyNames();
 
         cat.info("***System Environment As Seen By Java***");
         cat.debug("***Format: PROPERTY = VALUE***");
 
         while (enum.hasMoreElements()) {
             String key = (String) enum.nextElement();
             cat.info(key + " = " + System.getProperty(key));
         }
     }
 
 }
 
 ############################################################
   Log4J 默认情况下可以记录五个层次（由低到高）的日志消息。
   1) debug
   2)info
   3)warn
   4)error
   5)fatal
 
   在TestLoggin.class的目录中保存下列行在一个名字为log4j.properties 文件中.默认情况下，当你在代码中使用getRoot()或getInstance("category_name")时，Log4j会在应用程序的classpath中查找该文件：
 ############################################
 log4j.rootCategory=DEBUG, dest1
 log4j.appender.dest1=org.apache.log4j.ConsoleAppender
 log4j.appender.dest1.layout=org.apache.log4j.PatternLayout
 ############################################
 ConsoleAppender指定的是控制台附加器，即日志消息会输出到控制台上，而PatternLayout则指定了消息输出的格式，默认情况下格式为%m%n,%m指定的是消息内容，%n指定的是操作系统平台上的换行符,这里更类似于C语言中的输出控制语句。
   现在，你可以编译并且运行TestLogging.java了，你可以获得以下输出结果：
 
 Start of main()
 Just testing a log message with priority set to INFO
 Just testing a log message with priority set to WARN
 Just testing a log message with priority set to ERROR
 Just testing a log message with priority set to FATAL
 Calling init()
 ***System Environment As Seen By Java***
 ***Format: PROPERTY = VALUE***
 java.runtime.name = Java(TM) 2 Runtime Environment, Standard Edition
 sun.boot.library.path = c:/jdk1.3/jre/bin
 java.vm.version = 1.3.0_02
 java.vm.vendor = Sun Microsystems Inc.
 ... and so on
 
   如果想打印消息的层次如debug,info,error等，那可以在log4j.properties 文件的最后一行上增加如下一行：
 log4j.appender.dest1.layout.ConversionPattern=%-5p: %m%n
 这一行覆盖了默认的消息输出格式%m%n,%p指定的是打印消息的层次（info,debug...,其中-5指定的是五个字符的宽度，-指定的是左对齐),%m指定的是消息的内容，%n指定的则是操作系统平台上的换行符.
   当作完这些工作后，无须重新编译TestLogging.java，再次运用TestLogg，会得到以下不出的输出结果：
 DEBUG: Start of main()
 INFO : Just testing a log message with priority set to INFO
 WARN : Just testing a log message with priority set to WARN
 ERROR: Just testing a log message with priority set to ERROR
 FATAL: Just testing a log message with priority set to FATAL
 DEBUG: Calling init()
 INFO : ***System Environment As Seen By Java***
 DEBUG: ***Format: PROPERTY = VALUE***
 INFO : java.runtime.name = Java(TM) 2 Runtime Environment, Standard Edition
 INFO : sun.boot.library.path = c:/jdk1.3/jre/bin
 INFO : java.vm.version = 1.3.0_02
 INFO : java.vm.vendor = Sun Microsystems Inc.
 ... and so on
 
   如果不想输出日志的DEBUG与INFO消息，那么可以修改"log4j.rotCategory=DEBUG,dest1"为：
 log4j.rootCategory=WARN,dest1
   该行文件告诉Log4j跳过层次低于WARN的消息输出，也就是说如DEBUG,INFO层次的消息将不会产生输出，再次运行TestLogging.class，得到以下结果：
 ####################
 WARN : Just testing a log message with priority set to WARN
 ERROR: Just testing a log message with priority set to ERROR
 FATAL: Just testing a log message with priority set to FATAL
 ####################
 
 第二部分 Log4j 详解
   Log4j有三个主要的组件：category ,附件器和布局。
   在程序中，你可以初始化一个category 并且调用它的各种日志方法来将消息字符串记录到日志中。
   一个category可以被配置用来输出到多个目标，这些日志目标在Log4j框架中被称为附件器,这些附件器可以包括控制台、文本文件、HTML文件、XML文件甚至是Windows平的事件日志系统，甚至可以被作为邮件被发送。而这些所有的目标都是通过log4j.properties文件来进行配置，对于使用Log4j框架的程序来讲只是简单地调用类似于info()、debug()等的方法。
   附件器类可以是ConsoleAppender, FileAppender, SMTPAppender, SocketAppender, NTEventLogAppender, SyslogAppender, JMSAppender, AsyncAppender 和 NullAppender等。  附件器类可以使用布局（layout）来在发送消息到目标之前进行格式化。例如HTMLLayout将会把消息格式化为HTML 格式。
   除了可以记录消息字符串到日志文件之外，同时还可以记录日期、时间、消息层次、类名、源代码的行数、方法名称、线程名称以及其它信息，而具体的输出需要由附件器的布局管理器来配置。
    category的名字是大小写区分以"."分隔的一个字符串。一般情况下我们通常使用your_class_name.class.getName()来获得一个JAVA类名来作为category的名字，例如testproj.util.test。
   Each word in the category name is said to be an ancestor of the subsequent words and a parent of the immediately following word. This is important because Log4j has this concept of inheriting priorities and appenders from ancestors until overridden in a particular category.
   有一个没有名称的category叫root,它就像xml的document元素，是所有category的祖先。
   可以使用以下代码来初始一个根category或指定的category。
 ################
   Category cat = Category.getRoot();
 Category cat2 = Category.getInstance("your.category.name");
 ###################
   代表层次的常量由高到次是FATAL、ERROR、WARN、INFO和DEBUG，可以在log4j.properties中指定category所属的层次，例如指定log4j.rootCategory=WARN,simple则意味调用root这个category的程序只会记录WARN及WARN以上的消息。如果没有为一个category指定默认的category，那么category将会从其父category来继承。
    常见的Category类的日志方法有：
   public void log(Priority p, Object message);
 
 // Convenient shortcuts to the generic logging method
 public void debug(Object message);
 public void info(Object message);
 public void warn(Object message);
 public void error(Object message);
 public void fatal(Object message);
 
   log4j 只记录层次与预设层次相等或更高级别的消息，如以下代码：
 Category cat = Category.getRoot();
 cat.setPriority(Priority.ERROR);//设置预设层次为ERROR级
 // Later...
 //cat.info("Started processing..."); //这条消息将不会输出，ERROR
 cat.error("User input is erroneous!"); //消息输出，层次相等
 cat.fatal("Cannot process user input.  Program terminated!"); //消息输出，层次高于预设层次
 
 
 第三部分 Log4j 配置
   所有的配置工作应该在log4j.properties文件中完成，而该文件一般须放在应用程序的相同的目录中。
   在日志系统使用之前，我们必须首先配置log4j.配置log4j意味着增加附件器到Category并且为每一个Category设置一个Layout。
   category之间是有继承关系，但他们增加到log4j.properties文件中的顺序是不固定的。
 示例一:
 #############################################################
 # 设置log4j的根category所使用的预设层次是DEBUG,而只使用A1这个附件器.
 log4j.rootCategory=DEBUG, A1
 #附件器A1被设置为控制台附件器。
 log4j.appender.A1=org.apache.log4j.ConsoleAppender
 #附件器使用的布局是PatternLayout,即模式布局
 log4j.appender.A1.layout=org.apache.log4j.PatternLayout
 #附件器A1的模式是%-4r [%t] %-5p %c %x - %m%n,其中%m代表消息字符串，%n代表换行符,其它以%开头的字符代表的含义如下文。
 log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
 ################################################################# 
  示例二：
 #########################################################
 #### Use two appenders, one to log to console, another to log to a file
 log4j.rootCategory=debug, stdout, R
 # Print only messages of priority WARN or higher for your category
 log4j.category.your.category.name=WARN
 # Specifically inherit the priority level
 #log4j.category.your.category.name=INHERITED
 #### First appender writes to console
 log4j.appender.stdout=org.apache.log4j.ConsoleAppender
 
 log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
 # Pattern to output the caller's file name and line number.
 log4j.appender.stdout.layout.ConversionPattern=%5p [%t] (%F:%L) - %m%n
 #### Second appender writes to a file
 log4j.appender.R=org.apache.log4j.RollingFileAppender
 log4j.appender.R.File=example.log
 # Control the maximum log file size
 log4j.appender.R.MaxFileSize=100KB
 # Archive log files (one backup file here)
 log4j.appender.R.MaxBackupIndex=1
 log4j.appender.R.layout=org.apache.log4j.PatternLayout
 log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
 ########################################################
 第四部分 Log4j中有用的Layout
   一些有用的layout有TTCCLayout, HTMLLayout, PatternLayout, SimpleLayout 和 XMLLayout.
   其中SimpleLayout和PatternLayout忽略JAVA throwable 接口派生出来的errors和Exceptions.HTMLLayout和XMLLayout处理这些异常。
   SimpleLayout的输出中包含日志消息的层次，紧跟着“-”后面的日志消息字符串。例如：
 DEBUG - Hello World Message
   Patternlayout 可以根据输出的模式字符串来决定消息的输出，模式字符串类似于C语言中的模式字符串。例如PatternLayout中如果使用模式字符串“%r [%t] %-5p %c -%m%n”会输出以下消息：
 176 [main] INFO  org.foo.Bar -Located nearest gas station
 以下对各域作一下解释：
 1）%r输出程序开始执行之后的微秒数
 2）%t输出当前线程的名称
 3）%-5p输出消息的层次。
 4）%c 输出category的名称
 5)-%m及s是日志消息本身,%n是换行符。
   当前在模式字符串中你可以嵌入任何想要输出的字符。
   模式字符串中的模式如下：
 %m:消息本身
 %p:消息的层次
 %r:从程序开始执行到当前日志产生时的时间间隔（微秒）
 %c:输出当前日志动作所在的category名称。例如：如果category名称是"a.b.c","%c{2}"将会输出"b.c". {2}意谓着输出“以点分隔开的category名称的后两个组件”,如果 {n}没有，将会输出整个category名称.
 %t:输出当前线程的名称
 %x:输出和当前线程相关联的NDC(具体解释见下文),尤其用到像java servlets这样的多客户多线程的应用中。
 %n:输出平台相关的换行符。
 %%:输出一个"%"字符
 %d:输出日志产生时候的日期，当然可以对日期的格式进行定制。例如：%d{HH:mm:ss,SSSS}或者是%d{dd MMM yyyy HH:mm:ss,SSSS},如果没有指定后面的格式，将会输出ISO8601的格式。
 %l:输出位置信息，相当于%C.%M(%F:%L)的组合。
 %C:输出日志消息产生时所在的类名，如果类名是“test.page.Class1”%C{1}表示输出类名"Class1",%C{2}输出"page.Class1",而%C则输出"test.page.Class1"。
 %M:输出日志消息产生时的方法名称
 %F:输出日志消息产生时所在的文件名称
 %L:输出代码中的行号
    可以在%与模式字符之间加上修饰符来控制其最小宽度、最大宽度、和文本的对齐方式。如：
    1)%20c：指定输出category的名称，最小的宽度是20，如果category的名称小于20的话，默认的情况下右对齐。
   2) %-20c:指定输出category的名称，最小的宽度是20，如果category的名称小于20的话，"-"号指定左对齐。
   3) %.30c:指定输出category的名称，最大的宽度是30，如果category的名称大于30的话，就会将左边多出的字符截掉，但小于30的话也不会有空格。
   4)%20.30c:如果category的名称小于20就补空格，并且右对齐，如果其名称长于30字符，就从左边交远销出的字符截掉。
   4)%20.30c:
 
 
 
 第五部分 Log4j中附件器及相关的键值参数
 1.ConsoleAppender选项
 Threshold=WARN:指定日志消息的输出最低层次。
 ImmediateFlush=true:默认值是true,意谓着所有的消息都会被立即输出。
 Target=System.err：默认情况下是：System.out,指定输出控制台
 2.FileAppender 选项
 Threshold=WARN:指定日志消息的输出最低层次。
 ImmediateFlush=true:默认值是true,意谓着所有的消息都会被立即输出。
 File=mylog.txt:指定消息输出到mylog.txt文件。
 Append=false:默认值是true,即将消息增加到指定文件中，false指将消息覆盖指定的文件内容。
 3.RollingFileAppender 选项
 Threshold=WARN:指定日志消息的输出最低层次。
 ImmediateFlush=true:默认值是true,意谓着所有的消息都会被立即输出。
 File=mylog.txt:指定消息输出到mylog.txt文件。
 Append=false:默认值是true,即将消息增加到指定文件中，false指将消息覆盖指定的文件内容。
 MaxFileSize=100KB: 后缀可以是KB, MB 或者是 GB. 在日志文件到达该大小时，将会自动滚动，即将原来的内容移到mylog.log.1文件。
 MaxBackupIndex=2:指定可以产生的滚动文件的最大数。
 4.DailyRollingFileAppender 选项
 Threshold=WARN:指定日志消息的输出最低层次。
 ImmediateFlush=true:默认值是true,意谓着所有的消息都会被立即输出。
 File=mylog.txt:指定消息输出到mylog.txt文件。
 Append=false:默认值是true,即将消息增加到指定文件中，false指将消息覆盖指定的文件内容。
 DatePattern='.'yyyy-ww:每周滚动一次文件，即每周产生一个新的文件。当然也可以指定按月、周、天、时和分。即对应的格式如下：
 1)'.'yyyy-MM: 每月
 2)'.'yyyy-ww: 每周
 3)'.'yyyy-MM-dd: 每天
 4)'.'yyyy-MM-dd-a: 每天两次
 5)'.'yyyy-MM-dd-HH: 每小时
 6)'.'yyyy-MM-dd-HH-mm: 每分钟
 5.PatternLayout 选项
  ConversionPattern=%m%n :指定怎样格式化指定的消息。
 6.HTMLLayout 选项
 LocationInfo=true:默认值是false,输出java文件名称和行号
 Title=my app file: 默认值是 Log4J Log Messages.
 7.XMLLayout  选项
 LocationInfo=true:默认值是false,输出java文件和行号
 
 第六部分 Log4j配置案例解析
 #log4j.debug=true
 #log4j.disable=fatal
 #log4j.additivity.TestLogging=false
 
 log4j.rootCategory=, dest1
 log4j.category.TestLogging=DEBUG, dest1
 log4j.appender.dest1=org.apache.log4j.ConsoleAppender
 #log4j.appender.dest1.layout=org.apache.log4j.SimpleLayout
 log4j.appender.dest1.layout=org.apache.log4j.PatternLayout
 #log4j.appender.dest1.layout.ConversionPattern=%-5p %l %x: %m%n
 
 
 !----------------------####### END OF PROPERTIES #######----------------------!
 
 
 ###############################################################################
 # Below I document in more detail how to write a log4j configuration file.    #
 # SELECTIVELY copy lines beginning with #, paste and uncomment them above.    #
 ###############################################################################
 
 !-----------------------------------------------------------------------------!
 ! PLACE THIS FILE ANYWHERE IN CLASSPATH                                       !
 ! Appenders are additive by default.                                          !
 ! Priorities are inherited until overridden in a category.                    !
 ! In ${property_key}, the value of the key can be defined as a system         !
 ! property or in this file itself.  System properties are searched first and  !
 ! then this file.                                                             !
 !-----------------------------------------------------------------------------!
 
 
 
 !-----------------------------------------------------------------------------!
 ! Configure log4j's operation at the meta level                               !
 !-----------------------------------------------------------------------------!
 ! Observe log4j parsing this file
 #log4j.debug=true
 ! Set this to false for log4j to actually obey the log4j.disable property(next)
 #log4j.disableOverride=false
 ! Disable all logging in all categories for messages with priority equal to
 ! or lower than the one given here
 #log4j.disable=INFO
 
 
 
 !-----------------------------------------------------------------------------!
 ! Configure categories (loggers)                                              !
 !-----------------------------------------------------------------------------!
 
 ! ROOT CATEGORY (Usually sufficient to set this one only)
 ! Here, logs messages with priority DEBUG (default) or higher
 #log4j.rootCategory=, dest1
 ! Or,
 #log4j.rootCategory=debug, dest1, dest2
 
 ! YOUR CATEGORIES (to customize logging per class/pkg/project/etc)
 ! Here, overrides ancestor's priority and makes it WARN or higher for this cat.
 #log4j.category.TestLogging=WARN, dest3
 ! Or,
 #log4j.category.TestLogging=DEBUG, dest3
 
 !--------DON'T DO THIS!!!  APPENDERS ARE ADDITIVE BY DEFAULT!!!---------------!
 ! It will write the same log message TWICE to dest1. Once for root, then for  !
 ! this category.                                                              !
 !#log4j.category.TestLogging=DEBUG, dest1, dest3                              !
 ! If you DO NOT want additivity for this category, say so                     !
 !#log4j.additivity.TestLogging=false                                          !
 !-----------------------------------------------------------------------------!
 
 
 
 !-----------------------------------------------------------------------------!
 ! Configure appenders (log destinations/targets) and their options            !
 !-----------------------------------------------------------------------------!
 
 ! WRITE TO CONSOLE (stdout or stderr)
 #log4j.appender.dest1=org.apache.log4j.ConsoleAppender
 #log4j.appender.dest1.ImmediateFlush=true
 
 ! WRITE LOG TO A FILE, ROLL THE FILE AFTER SOME SIZE
 #log4j.appender.dest2=org.apache.log4j.RollingFileAppender
 ! This appender will only log messages with priority equal to or higher than
 ! the one specified here
 #log4j.appender.dest2.Threshold=ERROR
 ! Specify the file name (${property_key} gets substituted with its value)
 #log4j.appender.dest2.File=${java.home}/log4j.log
 ! Don't append, overwrite
 #log4j.appender.dest2.Append=false
 ! Control the maximum log file size
 #log4j.appender.dest2.MaxFileSize=100KB
 ! Keep backup file(s) (backups will be in filename.1, .2 etc.)
 #log4j.appender.dest2.MaxBackupIndex=2
 
 ! WRITE LOG TO A FILE, ROLL THE FILE EVERY WEEK
 #log4j.appender.dest3=org.apache.log4j.DailyRollingFileAppender
 ! Specify the file name
 #log4j.appender.dest3.File=log4TestLogging2.html
 ! Control the maximum log file size
 #log4j.appender.dest3.MaxFileSize=300KB
 ! Rollover log file at the start of each week
 #log4j.appender.dest3.DatePattern='.'yyyy-ww
 
 
 
 !-----------------------------------------------------------------------------!
 ! Configure appender layouts (log formats) and their options                  !
 !-----------------------------------------------------------------------------!
 
 ! USE SIMPLE LOG FORMAT (e.g. INFO - your log message)
 #log4j.appender.dest1.layout=org.apache.log4j.SimpleLayout
 
 ! USE A C PRINTF STYLE PATTERN TO FORMAT LOG MESSAGE
 #log4j.appender.dest1.layout=org.apache.log4j.PatternLayout
 ! For a pattern layout, specify the pattern (Default is %m%n which is fastest)
 #log4j.appender.dest1.layout.ConversionPattern=%-5p: %m%n
 ! Or,
 #log4j.appender.dest1.layout.ConversionPattern=%-5p %6.10r[%t]%x(%F:%L) - %m%n
 
 #log4j.appender.dest2.layout=org.apache.log4j.PatternLayout
 #log4j.appender.dest2.layout.ConversionPattern=[%d{ISO8601}]%5p%6.6r[%t]%x(%F:%L) - %m%n
 ! Or, (the pattern below will slow down your app)
 #log4j.appender.dest2.layout.ConversionPattern=[%d{yyyy-mm-dd hh:mm},%6.6r]%-5p[%t]%x(%F:%L) - %m%n
 
 
 ! FORMAT LOG MESSAGES IN THE FORM OF AN HTML TABLE
 #log4j.appender.dest3.layout=org.apache.log4j.HTMLLayout
 ! Include Java file name and line number (Default is false)
 #log4j.appender.dest3.layout.LocationInfo=true
 ! Set
 #================================================================================