log4j2中文手册簿.docx

1、log4j2中文手册簿Log4j2使用手册一Log4j2介绍Log4j1.x 被广泛应用于应用程序，但是近年发展明显放缓，因为要维持较老java版本的使用，使得log4j1.x 的发展更困难。而作为其代替品， slf4j/logback 做出了许多必要改进，为什么还需要log4j2? 主要有以下几个原因 :(1) Log4j2被设计用作审计日志框架, log4j 和logback 在重载配置时，都会丢失日志时间，而log4j2不会。Logback中appenders中的异常对于应用来说是不可见的，log4j2可以配置异常向应用渗透。(2) Log4j2 包含基于 LMAX Disruptor

2、library 的下一代无锁 Asynchronous Loggers ，在多线程环境下， Asynchronous Loggers 相比slf4j / logback 提高了10倍以上的吞吐量，并且有着更低的延时。(3) Log4j2的插件机制，使得在不需要修改框架的情况下，通过添加 Appenders,Filters,Layouts,Lookups 轻松扩展框架。(4) 简单的插件配置，无需指定具体类名即可在configuration 中配置插件。(5) 支持自定义日志级别，可以在代码或者 configuration 中自定义日志级别。(6) 支持lambda表达式，java8的应用可以在

3、请求日志级别启用时使用 lambda表达式懒构建一个日志消息，不需要显示的日志级别检查，使得代码更简洁。(7) 支持消息对象，消息允许支持有趣和复杂的结构，传递到日志记录系统，并且可以高效的操作。用户可以自由创建消息类型和 编写Layouts, Filters and Lookups 来操作这些消息。(8) Log4j1在Appenders 上支持 Filters。 logback增加了 TurboFilters，允许在日志事件在处理前进行过滤。Log4j2可以配置 Filters 在Logger后者Appender 前运行。(9) 许多Logback的Appenders 不接受Layout，

4、并且只能按照固定格式发送日志数据。大部分 log4j2 接收Layout配置，允许日志数据按照任何所需格式传输。(10) Log4j1与logback 的 Layouts 是返回一个String 类型，这可能导致一些编码问题。Log4j2使用了简单的方式：返回一个 byte 数组。这以为着Layouts 可以用在几乎任何appenders ，而不仅仅是 写入OutputStream。(11) Syslog appender 支持 TCP与UDP,以及BSD syslog 和 RFC5424格式。(12) Log4j2 得益于java5的并发支持，将锁的可能降到最低水平。Log4j1 有已知的死

5、锁问题，Logback也需要使用synchronization 来保持在相当高的锁级别。(13) Apache 开源二Log4j2架构1. Log4j2类图应用程序调用Log4j API 时需要向LogManager 传入一个特定的名称来获取一个Logger实例。LogManager 会定位一个合适的 LoggerContext然后从中获取 Logger 。如果 Logger必须新建，那么与之关联的 LoggerConfig 遵守如下规则 : (1)与Logger名称完全相同。（2）父Logger 的名称。（3）Root LoggerConfig 。LoggerConfig 对象是根据 con

6、figuration 配置中的Logger 声明创建的。LoggerConfig 又与处理LogEvents 的 LoggerConfig 关联。2. 日志层次logging API 相比于 纯粹的System.out.println 最重要的不同是 : logging API 可以禁用一些log语句输出的同时允许其他一些语句块输出。这种能力建立在开发者按照一定规则将日志分类的基础上。Log4j1.x 的层次关系是通过 Loggers 之间的关系保持的。而 Log4j2.x 是通过 LoggerConfig 对象来维持这种层次关系的。Loggers 与 LoggerConfigs 都是带名称的

7、实体。Logger名称是大小写敏感的，并且符合如下命名层级规则：一个LoggerConfig 的名字是另外一个 LoggerConfig 名字 加上 . 和一些后缀字符。 那么这个 LoggerConfig 是另外的 LoggerConfig 的子类。 类似于 java 的 package 路径。 例如 : 一个 名称为 com.foo的 LoggerConfig 是 一个名称为 com.foo.Bar 的LoggerConfig 的父类。类似的， “java” 是java.util的父类和 java.util.Vector 的祖先类 。 开发人员对这样的命名方案应该很熟悉。Root Logg

8、erConfig 居于 LoggerConfig 分层的顶层。Root LoggerConfig 总是存在于每个 LoggerConfig的层次中 。任何一个与rootLoggerConfig相关联的Logger可以通过如下方式获得：Logger logger = LogManager.getLogger(LogManager.ROOT_LOGGER_NAME);也可以用如下简便方式：Logger logger = LogManager.getRootLogger();其他的 Logger 可以使用 LogManager.getLogger 的静态方法根据传入的名称获得。3. LoggerCo

9、ntextLoggerContext 作为日志系统的锚点(用于根据日志名称定位日志输出信息的Logger)，在不同的环境中，一个应用系统中可能存在多个有效的 LoggerContexts，4. Configuration每个 LoggerContext有一个有效的Configuration。 Configuration包括所有的 Appenders，上下文过滤器，LoggerConfigs 与 包含StrSubstitutor的引用信息。在配置重载期间，两个Configuration共存，一旦所有的 Logger重定向到新的Configuration，旧的Configuration将停用和丢弃

10、。5. LoggerLoggers 是调用 LogManager.getLogger 静态方法创建的。Logger 本身不直接执行动作。它只有一个名称，并于一个LoggerConfig相关联。它继承自AbstractLogger ，当 configuration 被修改时，Loggers将关联修改后的 LoggerConfig，从而改变这个 Loggers的行为。获取Loggers：使用相同的名称调用 LogManager.getLogger 方法，总是返回完全相同的Logger对象。例如：Logger x = LogManager.getLogger(wombat);Logger y = L

11、ogManager.getLogger(wombat);X和y 指向完全相同的 Logger 对象。Log4j 配置环境通常是在应用程序初始化时完成的。最好的方式是读取配置文件。Log4j很容易通过类名来命名，这可以在每个类初始化的时候完成Logger的初始化，Logger 的名称就等于类的完整路径，这是一个定义Logger的简单有效的方式。当为日志文件输出具有 Logger 名称的日志时，这种命名策略可以很容易看出一个 日志消息的来源。当然这只是一种比较常见的日志命名方式，log4j并没有对此进行限制，开发人员可以按照需求进行命名。因为使用类名命名 Logger是一个习惯用法。一个便利的方法

12、是使用LogManager.getLogger() 来获取类的全路径名称的 Logger。目前为止，使用类名来作为Logger 的名称是最好的方式。6. LoggerConfig当Logger对象在 logging configuration 中被定义时， LoggerConfig对象同时被创建。LoggerConfig包含一组Filters 来过滤传递到 Appenders 的LogEvent。LoggerConfig使用一组Appenders用来处理这些事件。Log LevelsLoggerConfigs 被分配一个日志级别，包括 ： TRACE, DEBUG, INFO, WARN, E

13、RROR, FATAL 。 Log4j2 也支持自定义日志级别，另一种获得更多日志粒度的方式是使用 Markers 。Log4j1 与logback 都有日志级别继承的概念。在Log4j2中，因为 Loggers 和LoggerConfigs是2个不同的对象，所以这个概念的实现有所不同。但是因为每个Loggers都关联一个相应的 LoggerConfig， 所以最终效果是相同的。如果一个 root LoggerConfig 没有配置日志级别，将分配一个默认级别。Logger NameAssigned LoggerConfigLoggerConfig LevelLogger Levelrootr

14、ootDEBUGDEBUGXrootDEBUGDEBUGX.YrootDEBUGDEBUGX.Y.ZrootExample 1在 Example1 中， 仅配置了root logger 与其日志级别，所有的Loggers 都会引用root LoggerConfig ，并使用其日志级别。Logger NameAssigned LoggerConfigLoggerConfig LevelLevelrootrootDEBUGDEBUGXXERRORERRORX.YX.YINFOINFOX.Y.ZX.Y.ZWARNWARNExample 2在Example2中， 每个Logger 都有其对应的 Log

15、gerConfig和相应的日志级别。Logger NameAssigned LoggerConfigLoggerConfig LevelLevelrootrootDEBUGDEBUGXXERRORERRORX.YXERRORERRORX.Y.ZX.Y.ZWARNWARNExample 3在 Example3 中，Logger root,X和X.Y.Z 都有与名称完全匹配的LoggerConfig配置，而 Logger X.Y 没有与其命名匹配的 LoggerConfig，所以使用拥有最长匹配度的 X 的LoggerConfig。Logger NameAssigned LoggerConfigL

16、oggerConfig LevellevelrootrootDEBUGDEBUGXXERRORERRORX.YXERRORERRORX.Y.ZXERRORERRORExample 4Example 4 中，root与X 各自有一个与名称完全匹配的 LoggerConfig ，而 X.Y与X.Y.Z 没有与名称完全匹配的 LoggerConfig， 所以使用与其名称有最长匹配度的 X 的LoggerConfig。Logger NameAssigned LoggerConfigLoggerConfig LevellevelrootrootDEBUGDEBUGXXERRORERRORX.YX.YIN

17、FOINFOX.YZXERRORERRORExample 5Example 5 中 root.X, 与X.Y 有与名字完全匹配的 LoggerConfig， 而 X.YZ 将与X 相匹配而不是 X.Y ， 因为路径匹配时按照 . 进行分割和匹配的。 Logger NameAssigned LoggerConfigLoggerConfig LevelLevelrootrootDEBUGDEBUGXXERRORERRORX.YX.YERRORX.Y.ZX.YERRORExample 6Example 6 中， X.Y 与 X.Y.Z 都没有配置相应的日志级别， 所以他们从 Logger X中继承了

18、日志级别 。下面的表格展示了 logEvent(垂直方向) 与 LoggerConfig（水平方向） 的过滤方式：Event LevelLoggerConfig LevelTRACEDEBUGINFOWARNERRORFATALOFFALLYESYESYESYESYESYESNOTRACEYESNONONONONONODEBUGYESYESNONONONONOINFOYESYESYESNONONONOWARNYESYESYESYESNONONOERRORYESYESYESYESYESNONOFATALYESYESYESYESYESYESNOOFFNONONONONONONO7. FilterL

19、og4j2 提供了 Filters， 可以 应用于 控制权传递到 LoggerConfig 之前，控制权传递到LoggerConfig 之后 但是在调用 Appenders 之前，控制权在传递到 LoggerConfig之后，但是在调用一个指定的 Appender 之前。 类似于防火墙的处理方式，每个 Filters可以返回三个结果的其中之一。Accept,DenyNeutral 。Accept 意味着 不会再调用其他Filters了，LogEvent 将被执行。Deny 意味着 立即忽略这个 LogEvent， 并将这个 LogEvent 的控制权交还给它调用者。Neutral 指LogEv

20、ent将传递给其他Filters， 如果没有别的Filters了，那么这个LogEvent将被执行。尽管一个 LogEvent 可能被一个Filter接收，但是这个LogEvent仍然没有被日志记录下来，发生这种情况的场景可能是LogEvent被 pre-LoggerConfig Filter 接收了，但是却被 LoggerConfig 拒绝了，或者被所有的 Appenders 拒绝了。8. Appender由logger的不同来决定一个loggingrequest是被禁用还是启用只是log4j2的情景之一。log4j2还允许将loggingrequest中log信息打印到不同的目的地中。在l

21、og4j2的世界里，不同的输出位置被称为Appender。目前，Appender可以是console、文件、远程socket服务器、ApacheFlume、JMS以及远程UNIX系统日志守护进程，数据库。 一个Logger可以绑定多个不同的Appender。可以通过调用当前Configuration的addLoggerAppender 方法为Logger增加一个 Appender。如果不存在一个与Logger名称相对应的LoggerConfig，那么相应的LoggerConfig将被创建，并且新增加的Appender将被添加到此新建的LoggerConfig中。然后，所有的Loggers将会被

22、通知更新自己的LoggerConfig引用（PS：一个Logger的LoggerConfig引用是根据名称的匹配长度来决定的，当新的LoggerConfig被创建后，会引发一轮配对洗牌）。某个logger 中被启用的logging request 将被转发到该Logger LoggerConfig相关联的的所有Appenders上，并且还会被转发到LoggerConfig的父级的Appenders上。换句话说，Appenders 将从LoggerConfig的层次结构中获得继承。例如，对LoggerConfigB来说，它的父级为A，A的父级为root。如果在root中定义了一个Appender

23、为console，那么所有启用了的loggingrequest都会在console中打印出来。另外，如果LoggerConfigA定义了一个文件作为Appender，那么使用LoggerConfigA和LoggerConfigB的logger的loggingrequest都会在该文件中打印，并且同时在console中打印。如果想避免这种遗传效应的话，可以在configuration文件中做如下设置：additivity=false这样，就可以关闭Appender的遗传效应了。具体解释如下 :Appender AdditivityThe output of a log statement of

24、LoggerLwill go to all the Appenders in the LoggerConfig associated withLand the ancestors of that LoggerConfig. This is the meaning of the term appender additivity.However, if an ancestor of the LoggerConfig associated with LoggerL, sayP, has the additivity flag set tofalse, thenLs output will be di

25、rected to all the appenders inLs LoggerConfig and its ancestors up to and includingPbut not the Appenders in any of the ancestors ofP.Loggers have their additivity flag set totrueby default.上面例子的详细表格解释如下：LoggerNameAddedAppendersAdditivityFlagOutput TargetsCommentrootA1not applicableA1The root logger

26、 has no parent so additivity does not apply to it.xA-x1, A-x2trueA1, A-x1, A-x2Appenders of x and root.x.ynonetrueA1, A-x1, A-x2Appenders of x and root. It would not be typical to configure a Logger with no Appenders.x.y.zA-xyz1trueA1, A-x1, A-x2, A-xyz1Appenders in x.y.z, x and root.securityA-secfa

27、lseA-secNo appender accumulation since the additivity flag is set tofalse.security.accessnonetrueA-secOnly appenders of security because the additivity flag in security is set tofalse.9. Layout通常，用户不止希望能定义log输出的位置，还希望可以定义输出的格式。这就可以通过将Appender与一个layout相关联来实现。Log4j中的 一个标准定义PatternLayout ，就允许用户使用一种类似C语

28、言printf函数的打印格式，如%r%t%-5p%c-%m%n格式在真实环境下会打印类似如下的信息：176 main INFO org.foo.Bar - Locatednearestgasstation.第一个字段是启动的毫秒数，第二个字段是日志请求的线程号， 第三个字段是日志请求级别，第四个是与日志请求相关联的日志名称， 在“-” 之后的内容就是日志内容。Log4j 有各种不同的 Layouts， 例如 : JSON, XML, HTML, 和Syslog (including the new RFC 5424 version).其他一些 appenders 例如 database con

29、nectors 会使用指定的字段替代 特定的文本布局。同样重要的是，要使得log4j的日志消息内容符合用户指定的标准。，例如：在你的工程中，你需要一个 Oranges 类型的日志对象，你就可以创建一个 OrangeMessage， 可以接受Orange实例并且传递到log4j， Orange 对象就会被格式化为一个适当的字节数组。10. StrSubstitutor and StrLookupStrSubstitutor 类与 StrLookup 接口是来自 Apache Commons Lang ， 并且被修改为支持 LogEvents 的运算。此外 来自 Apache Commons Co

30、nfiguration的 Interpolator类允许StrSubstitutor 运算来着多个 StrLookups 的变量，它也被修改支持 LogEvents的运算。Log4j2 提供了一种机制，可以使得configuration 引用 来自System Properties, the configuration file, the ThreadContext Map, StructuredData 中的变量。当 configuration 被加载或者 每个LogEvent 运行时， 这个变量将被解析。 如果这个日志组件可以处理这个变量。三Log4j2 APILog4j2 API 提供了应用程序使用的接口，也提供了创建一个日志实现所需的适配器组件，Log4j2 解耦了API 及其 实现之间的关系