译者：醉了~白
E-MAIL：ENVELOP@163.COM
中文标题：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
