log4j使用文档

一：Log4j的组件介绍


A:)Log4j的三个重要组件—— Loggers, Appenders, Layouts

这三个组件协同的工作，使得开发者能够依据信息类别和级别去纪录信息，并能够
运行期间，控制信息记录的方式已经日志存放地点。

B:)记录器层次（Logger hierarchy）

几乎任何纪录日志的API得功能都超越了简单的System.out.print语句。允许有选
择控制的输出日志信息，也就是说，某的时候，一些日志信息允许输出，而另一
些则不允许输出。这就假设日志纪录信息之间是有分别的，根据开发者自己定义
的选择标准，可以对日志信息加以分类。

纪录器的命名是依据实体的。它有两个独特点：（1）总是存在的
（2）能够被重新找回。可以通过访问类的静态方法 Logger.getRootLogger 重新得到。
其他的纪录器通过访问静态方法 Logger.getLogger 被实例话或被得到，这个方法将希
望获得的记录器的名称作为参数。一些Logger类的方法描述如下：
public class Logger {
// Creation & retrieval methods:
public static Logger getRootLogger();
public static Logger getLogger(String name);
// printing methods:
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);

// generic printing method:
public void log(Level l, Object message);
}

记录器被赋予级别，这里有一套预定的级别标准：DEBUG, INFO, WARN, ERROR and FATAL ，
这些是在 org.apache.log4j.Level 定义的。你可以通过继承Level类定义自己的级别标准，
虽然并不鼓励这么做。
如果给定的记录器没有被赋予级别，则其会从离其最近的拥有级别的ancestor处继承得到。
如果ancestor也没有被赋予级别，那么就从根记录器继承。所以通常情况下，为了让所有
的记录器最终都能够被赋予级别，跟记录器都会被预先设定级别的。比如我们在操作properties
文件中，会写这么一句：log4j.rootLogger=DEBUG, A1 。实际上就这就指定了root Logger和
root Logger level。

****注意:Logger level的设定使得做Logger是有选择，如果设定为LOG_LEVEL,则Logger level
在LOG_LEVEL以下的都将进行输出。最低优先级为DEBUG.最高为FATAL.
#FATAL 0
#ERROR 3
#WARN 4
#INFO 6
#DEBUG 7

Appenders

Log4j允许记录信息被打印到多个输出目的地，一个输出目的地叫做Appender。目前的Log4j
存在的输出目的地包括：控制台（Console）,文件（File），GUI Componennt，Remote Socket
Server，JMS，NT Event Logger，and Remote Unix Syslog daemons。
多个Appender可以绑定到一个记录器上（Logger）。
通过方法 addAppender（Logger.addAppender） 可以将一个Appender附加到一个记录器上。
每一个有效的发送到特定的记录器的记录请求都被转送到那个与当前记录器所绑定的Appender上。
（Each enabled logging request for a given logger will be forwarded to all the appenders
in that logger as well as the appenders higher in the hierarchy），换句话说，Appender
的继承层次是附加在记录器继承层次上的。举个例子：如果一个Console Appender被绑定到根记录器
（root Logger），那么所有的记录请求都可以至少被打印到Console。另外，把一个file Appender
绑定到记录器C，那么针对记录器C（或C的子孙）的记录请求都可以至少发送到Console Appender
和file Appender。当然这种默认的行为方式可以跟改，通过设定记录器的additivity flag
（Logger.setAdditivity）为false，从而可以使得Appender的不再具有可加性（Additivity）。

下面简要介绍一下Appender Additivity。
Appender Additivity：记录器C所记录的日志信息将被发送到与记录器C以及其祖先（ancestor）
所绑定的所有Appender。 但是，如果记录器C的祖先，叫做P，它的additivity flag被设定为
false。那么，记录信息仍然被发送到与记录器C及其祖先，但只到达P这一层次，包括P在内的
记录器的所有Appender。但不包括P祖先的。通常，记录器的additivity flag的被设置为true。

Layouts
这一块主要是介绍输出格式的。PatternLayout，Log4j标准的分配器，可以让开发者依照
conversion patterns去定义输出格式。Conversion patterns有点像c语言的打印函数。
参看配置文件的java properties，如下面的两行：
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d %-5p [%t] %C{2} (%F:%L) - %m%n
第一行就指定了分配器，第二行则指定了输出的格式。
有关输出格式的定义可以参考/org/apache/log4j/PatternLayout.html

二：配置
A:)在Web Application 中使用log4j
Step 1:
配置log4j配置文件
log4j.properties
=========================
# Set root logger level to DEBUG and its only appender to A1
#log4j中有五级logger
#FATAL 0
#ERROR 3
#WARN 4
#INFO 6
#DEBUG 7
log4j.rootLogger=DEBUG, A1
#这一句设置以为着所有的log都输出
#如果为log4j.rootLogger=WARN, A1 则意味着只有WARN,ERROR,FATAL
#被输出，DEBUG,INFO将被屏蔽掉.
# A1 is set to be a ConsoleAppender.
#log4j中Appender有几层
#ConsoleAppender输出到控制台
log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
#输出格式 具体查看log4j javadoc org.apache.log4j.PatternLayout
#d 时间 ....
log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n

================================另外一种配置
log4j.rootLogger=debug, stdout, R

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
#R 输出到文件
log4j.appender.R=org.apache.log4j.RollingFileAppender
log4j.appender.R.File=example.log

log4j.appender.R.MaxFileSize=100KB
# Keep one backup file
log4j.appender.R.MaxBackupIndex=1

log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n

Step 2:写启动的Servlet

public class InitServlet extends HttpServlet {

public void init() {
ServletContext sct = getServletContext();
String prefix = sct.getRealPath("/");
//log4j 配置文件存放目录
System.out.println("[....Log4j]: The Root Path: " + prefix);
System.out.println("[....Log4j]: InitServlet init start...");
String file = getInitParameter("log4j");
//log4j 配置文件
if (file != null) {
PropertyConfigurator.configure(prefix + file);
//根据配置初始化log4j
}

System.out.println("[....Log4j]: InitServlet Init Sucess...");

}

public void doGet(HttpServletRequest req, HttpServletResponse res) {

}

public void doPost(HttpServletRequest req, HttpServletResponse res) {

}
}

B:在一般的IDE中使用log4j,因为使用log4j需要做一些初始化，在Web Application
中这一部分初始化是有AppServer 启动是加载的。在IDE中，则我们在使用log4j
之前需要自己配置一下。 有两种方式配置log4j初始化，一种是通过加载配置文件。
另外一种是配置一个Appender.
如下文件：
public final class Lo4jTest {
private static String CLASS_NAME = "com.bingo.test.Lo4jTest";
private static Logger log = Logger.getLogger(CLASS_NAME);
//在Web Application 中下面的pattern是在log4j的配置文件中配置的。
//现在我们手动配置
private static String pattern="%-4r [%-t] [%p] [%c] [%x] - [%m]%n";
private static String pattern2="%-d{yyyy-MM-dd HH:mm:ss} [%c]-[%p] %m%n";
//设置输出层
private static String profile="e:/Xml/log4j.properties";
//根据配置文件做配置
private static ConsoleAppender consAppender =
new ConsoleAppender(
new PatternLayout(pattern2));

public static void main(String[] args) {
//配置log4j
BasicConfigurator.configure(consAppender);
// void configure(Appender appender);
// void configure();
//配置时log4j提供了两种方式
//后一种比较简单，输出的信息不够详细
//我们可以使用前一种输出我们希望的格式
//PropertyConfigurator.configure(profile);
//上面的是根据配置文件做配置
log.debug("Log4j Debug.");
log.error("Log4j Error.");
log.warn("Log4j Warn.");
log.info("Log4j Info.");
log.fatal("Log4j Fatal.");
//修改log4j.properteis的设置如下一行,把DEBUG 修改为ERROR,INFO,WARN,FATAL
//将会输出不同的结果
//log4j.rootLogger=DEBUG, A1
}
}

//使用pattern2上面的输出结果如下
2002-08-30 13:49:09 [com.bingo.test.Lo4jTest]-[DEBUG] Log4j Debug.
2002-08-30 13:49:09 [com.bingo.test.Lo4jTest]-[ERROR] Log4j Error.
2002-08-30 13:49:09 [com.bingo.test.Lo4jTest]-[INFO] Log4j Info.
2002-08-30 13:49:09 [com.bingo.test.Lo4jTest]-[FATAL] Log4j Fatal.
//假如我们使用pattern输出如下:
0 [main] [DEBUG] [com.bingo.test.Lo4jTest] [] - [Log4j Debug.]
0 [main] [ERROR] [com.bingo.test.Lo4jTest] [] - [Log4j Error.]
0 [main] [INFO] [com.bingo.test.Lo4jTest] [] - [Log4j Info.]
0 [main] [FATAL] [com.bingo.test.Lo4jTest] [] - [Log4j Fatal.]

三：使用log4j
在实际使用过程中其实非常简单

1:)如下定义log,在log4j1.2以前使用Category,log4j1.2以后使用Logger代替
private static String CLASS_NAME = "com.bingo.test.Lo4jTest";
//log4j1.2
private static Logger log = Logger.getLogger(CLASS_NAME);
//lo4j1.2以前
private static Category log =Category.getInstance(CLASS_NAME);
//取得一个Category or Logger有几种方式，根据自己需要使用

2:)写日志
log.debug("Log4j Debug.");
log.info("Log4j Info.");
log.warn("Log4j Warn.");
log.error("Log4j Error.");
log.fatal("Log4j Fatal.");
//void debug(Object message)
//Log a message object with the DEBUG level.
//void debug(Object message, Throwable t)
//Log a message object with the DEBUG level including the
//stack trace of the Throwable t passed as parameter.

四：注意事项
1:在具体使用中注意不同的信息使用不同的log方式，选择debug,error,warn,
info,fatal中的一种，以后可以根据需要屏蔽部分输出
2:开发过程中尽量输出到控制台，运行过程中则修改配置使其输出到文件.
3:定义log尽量使用文件名作为参数，这样容易查找错误.