(原创连载)LOG4J文档翻译

这是Log4j（版本：log4j-1.2.9）的官方英文文档，打算利用下班时间把它翻译一下，如果有翻译不对的地方，还请各位网友给小弟指出，谢谢大家

Loggers, Appenders and Layouts(记录器，渲染器，样式)

Log4j 有三大组件：Loggers,Appenders and layouts(记录器，渲染器，样式),这三种组件组成在一起使开发人员能够通过日志类型和日志级别来记录日志。并控制日志在运行时显示的格式和显示的位置。

Logger hierarchy　（日志层次结构）

任何日记API最主要的优点都是可以控制最简单的System.out.println()显示和不显示，这种实现假定一种空白日志，也就是说，不记录一些日志语句，也就是通过开发者选择的某种标准来记录日志，观察了这种需求后。在以前会我们我们选择Category作为包的核心部分，然而，在log4j 1.2版本以后。Logger 类就已经替代了Category类，但是这些和先前的log4j版本相似。Logger类可以看作是Category类的一个别名。

记录器(Logger)被叫做实体。记录器(Logger)的名字是大小写敏感并且有以下的层次规则：

命名层次

如果一个记录器的名字带有点并且是其它记录器的前缀，那么这个记录器就叫祖先记录器。父记录器是指在一个祖先记录器和子记录器之间不在有其它祖先记录器。

例如，一个叫“com.foo”的记录器是一个“com.foo.Bar”的父记录器，同样地，“java”是一个"java.util"和"java.util.Vector"的祖先。这种命名模式对于大多数程序员来说是熟悉的。

root logger位于所以记录器之上，有二种特性：

1.总是存在

2.不能用名字重新取得

调用Logger.getRootLogger的静态方法得到。其它的记录器用Logger.getLogger静态方法实体化或得到，此方法接收一个想要得到的记录器名字。Logger类的一些基本方法如下：

package org.apache.log4j;

  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);
}

 可以为记录器指定一个级别，一系列可以指定的级别是定义在org.apache.log4j.Level类中的： DEBUG, INFO, WARN, ERROR and FATAL ，你可以通过继承Leverl类来定义自己的级别，但是我们不鼓励你这么做，我们一会要解释一种更好的方案。

如果一个给定的记录器没有指定级别，他将从最进的祖先继承，更正式地：

日志继承层次：

　　给定的一个记录器C的通过继承得到的记录级别和第一个不为空的记录器级别相同。 从C开始向上推进一直达到根记录器(root logger)

 

 为了确保所有的记录器都持有一个日志记录级别，那么总是要指定根记录器的日志记录级别。

以下四个表格是通过以上规则列出的各种指定日志级别和继承日志级别

Logger
nameAssigned
levelInherited
level Example 1

root	Proot	Proot
X	none	Proot
X.Y	none	Proot
X.Y.Z	none	Proot

上面的例子1中，只有根记录器指定了日志级别，它的值是,Proot,将被记录器X,X.Y和X.Y.Z继承

Logger
nameAssigned
levelInherited
level Example 2

root	Proot	Proot
X	Px	Px
X.Y	Pxy	Pxy
X.Y.Z	Pxyz	Pxyz

在例子2中，所有的记录器被指定了一个日志级别，就没有必要继承了。

Logger
nameAssigned
levelInherited
level Example 3

root	Proot	Proot
X	Px	Px
X.Y	none	Px
X.Y.Z	Pxyz	Pxyz

在例子3中，根记录器(root)，X和X.Y.Z分别指定了记录级别Proot,Px和Pxyz。记录器从X.Y从你记录器X继承日志记录级别

Logger
nameAssigned
levelInherited
level Example 4

root	Proot	Proot
X	Px	Px
X.Y	none	Px
X.Y.Z	none	Px

在例子4中，根记录器(root)和X记录器分别被指定了记录器Proot和Px。记录器X.Y和X.Y.Z从他们最近的指定了记录级别的父记录器X继承了这个日志记录级别

日志请求（注：即记录日志）调用记录器实例的打印方法，这些打印方法是：debug,info,warn,error,fatal和log。

更精确的说，打印方法决定了日志的记录级别。例如，如果C是一个记录器实例，那么语句 c.info("...")是一个INFO级别的记录请求。

为了能够记录日志，日志请求级别一定要打于或等于记录器级别，否则，日志不能够记录，如果记录器没有指定日志记录级别，它会按层次继承一个日志记录级别。规律总结如下：

基本选定规则：

日志请求级别为Ｐ(指定或继承的都可以)日志记录器级别为Ｑ,如果Ｐ>=Ｑ则可以记录日志

这是Log4j的内在规则，这种级别是已经定义好了的，标准的级别是这样的：DEBUG<INFO<WARN<ERROR<FATAL

下面是这种规则的一个例子：

   // get a logger instance named "com.foo"
   Logger  logger = Logger.getLogger("com.foo");

   // Now set its level. Normally you do not need to set the
   // level of a logger programmatically. This is usually done
   // in configuration files.
   logger.setLevel(Level.INFO);

   Logger barlogger = Logger.getLogger("com.foo.Bar");

   // This request is enabled, because WARN >= INFO.
   logger.warn("Low fuel level.");

   // This request is disabled, because DEBUG < INFO.
   logger.debug("Starting search for nearest gas station.");

   // The logger instance barlogger, named "com.foo.Bar",
   // will inherit its level from the logger named
   // "com.foo" Thus, the following request is enabled
   // because INFO >= INFO.
   barlogger.info("Located nearest gas station.");

   // This request is disabled, because DEBUG < INFO.
   barlogger.debug("Exiting gas station search");

用同一个相同的名字去调用方法getLogger会返回同一个日志对象的引用

例如： 

   Logger x = Logger.getLogger("wombat");
   Logger y = Logger.getLogger("wombat");

x和y引用同一个日志(Logger)对象

因此，当你配置一个记录器后就可以在代码的任何地方引用它，而不必到处传递这个对象引用。Log4j记录器与生物上的父在子之前原理相反，你可以在任何地方配置和创建，事实上，父记录器将找到并连接到他的子孙，即便子孙在父记录器之后创建。

配置Log4j的配置是在应用程序初始化的时候，首选的方式是读取一个配置文件，马上将要讨论。

通过Log4j你可以很方便的用软件的组件来给记录器命名，用和类名相同的记录器名，就可以在各个类中静态的建立一个记录器实例，这是一种直接并易用的方式来定义记录器，这样日志就要按照记录器的名字来生成，这种命名策阅很容易定义日志的起源，然而，这只是一种可行的方法，虽然常用，但是Log4j并不限定开发者定义自己的记录器。开发者可以取自己期望的任何一个记录器。 

然而，通过类来给命名记录器是到现在最好的一种命名策略。

Appenders and Layouts（渲染器和样式）

让用户能够控制显示或不显示日志只是log4j的一部份功能，log4j把日志输出到不同的地方，用log4j的说法，输出地叫做渲染器（Appender）,当前的渲染器有：控制台（console）,文件（files）,图形组件，远程套节字服务器（remote socket server）,JMS，NT Event Loggers，和remote UNIX Syslog daemons，也呆以异步记录日志。

可以为一个记录器指定多个Appender

给一个记录器添加一个Appender的方法是addAppender，一次日志请求会输出到记录器所指定的所有Appender以及层次关系中继承的Appender。