Layout of Log4j

本文档使用Log4j版本为1.2.17

1. Layout介绍

Log4j Layout主要用来控制日志的序列化格式，比如时间、线程号、日志消息对齐方式等，是log4j体系结构中的核心组成部分之一。

Layout抽象类声明为:

1	public abstract class Layout implements OptionHandler

Layout实现了OptionHandler接口，OptionHandler仅包含一个方法activateOptions()。对实现了OptionHandler接口的模块，调用属性setter方法后，log4j的配置器类会调用此模块的activateOptions实现以激活配置。OptionHandler存在的原因是有些属性彼此依赖，在它们在全部加载完成之前是无法激活的，这个方法用于在模块变为激活和就绪之前用来执行任何必要任务的机制。比如：

某模块有字符串属性fileName属性，表示log4j用户配置的写出日志文件名，使用前需要创建File对象获取文件写出IO流，具体则是由activateOptions完成文件的打开等，具体可见log4j的FileAppender实现中对文件名和文件IO的操作。

Layout类的方法或接口如下，abstract修饰的需要具体子类实现:

//abstract修饰需要具体子类实现，将日志事件渲染为待打印的日志文本字符串，可写出到Appender
abstract public String format(LoggingEvent event )
//format函数返回的格式化文本类型，默认返回为”text/plain”
public String getContentType()
//针对HTMLLayout类的格式化输出，html字符串的头部，默认null
public String getHeader()
//针对HTMLLayout类的格式化输出，html字符串的尾部，默认null
public String getFooter()
//对于LayoutEvent中异常的处理模式，true表示忽略异常，异常会到达Appender，由Appender负责渲染为打印持久化字符串信息；false表示由Layout负责渲染异常信息。SimpleLayout、TTCCLayout、PatternLayout实现返回true;XMLLayout实现返回false，由Appender处理渲染异常消息。
abstract public boolean ignoresThrowable()
Layout是对序列化每一次LoggingEvent的抽象，核心是format方法，format作为抽象方法，由具体子类实现具体的序列化方式。具体子类有：

SimpleLayout
TTCCLayout
PatternLayout
XMLLayout
HTMLLayout
DateLayout
Layout继承体系

XMLLayout

XMLLayout实现了根据log4j.dtd序列化输出xml格式的日志文本，默认的log4j.dtd文件在/org/apache/log4j/xml/log4j.dtd目录下，注意，XMLLayout打印输出的并非完整XML文件，并不包括<?xml version=”1.0” ?>等XML头部，XMLLayout的目的是输出XML的部分片段，应用可将此片段整合嵌入到其它XML文件中。XMLLayout有成员属性：
locationInfo表示是否打印位置信息，即日志事件发生的代码文件名、日志记录点代码行号等信息，log4j配置文件中需要配置为LocationInfo
properties表示是否打印MDC中的Key-Value信息，默认为false，log4j配置文件中需要配置为Properties

注意：log4j的各个模块涉及的成员属性时，如果属性有set方法，一般表示此属性可通过log4j.properties进行配置，具体配置属性值为属性的setXXX方法去掉set前缀。

示例如上面的locationInfo和properties配置:

log4j.appender.Console.layout.LocationInfo=true
log4j.appender.Console.layout.Properties=true

XMLLayout继承自Layout的方法实现有：

//配置激活的接口实现，来自于OptionHandler interface，方法体为空
public void activateOptions()
//返回false，表示XMLLayout自己处理异常信息
public boolean ignoresThrowable()
public String format( final LoggingEvent event)
2.1 format实现

format按照日志message、NDC、getThrowableStrRep、日志位置信息、MDC的顺序，并按照XML格式序列化LoggingEvent。log4j实现时使用StringBuffer避免字符串拼接的开销（JAVA中String是不可变类），具体使用时设置了StringBuffer的默认长度即DEFAULT_SIZE = 256，最大长度UPPER_LIMIT = 2048。每次format函数调用时，如果当前StringBuffer容量未超过上限，则复用已有的StringBuffer并清空已有内容；如果当前StringBuffer容量超过UPPER_LIMIT上限，则创建一个新的StringBuffer将当前LoggingEvent 序列化到其中，目的是尽量减少内存的占用量。

if(buf.capacity() > UPPER_LIMIT) {
buf = new StringBuffer(DEFAULT_SIZE);
} else {
buf.setLength(0);
}
xml序列化中，对于属性如 timestamp=”1452874282177” level=“INFO”，为了保持生成的文本符合XML语法，需要对特殊字符进行转义处理。对于属性使用org.apache.log4j.helpers.Transform.escapeTags做转义。对于文本子元素如 <![CDATA[123]]>，使用org.apache.log4j.helpers.Transform.appendEscapingCDATA做转义，将message放在 <![CDATA[ 和 ]] 之间，避免文本破坏XML语法。

处理的XML特殊字符有（简单字符串替换）:

-> >
< -> <
& -> &
“ -> "
2.2 demo

demo java code:

Logger logger = Logger.getLogger(LayoutTest.class);
NDC.push(“ndc message”);
logger.info(“info:123”);
logger.warn(“warn:abc”);
logger.info(“exception”, new RuntimeException(“run time exception”));
demo log4j config:

log4j.rootLogger=INFO,Console
log4j.appender.Console=org.apache.log4j.ConsoleAppender
log4j.appender.Console.target=System.out
log4j.appender.Console.layout=org.apache.log4j.xml.XMLLayout
log4j.appender.Console.layout.LocationInfo=true
log4j.appender.Console.layout.Properties=true

demo 日志输出:

<![CDATA[info:123]]>

<![CDATA[ndc message]]>

<![CDATA[warn:abc]]>

<![CDATA[ndc message]]>

<![CDATA[error:xyz]]>

<![CDATA[ndc message]]>

<![CDATA[exception]]>

<![CDATA[ndc message]]>

<![CDATA[java.lang.RuntimeException: run time exception
at com.luohw.log4j.LayoutTest.test(LayoutTest.java:16)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
… …
at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:382)
at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:192)
]]>

HTMLLayout

HTMLLayout用于将每次的LoggingEvent序列化为HTML格式字符串，具体的内容组织为html的表格。生成的HTML文本为完整的一份HTML格式代码（不同于XMLLayout的部分片段），包含html、head、body、具体table信息等。一份HTML日志文档可以包含多条LoggingEvent序列化输出，但header和footer只会输出一次（具体是有Appender打开和关闭相关流时输出）。

注意：如果有Appender使用HTMLLayout，需要设置Appender的字符编码为UTF-8 或者 UTF-16，否则非ASCII字符会产生乱码。

locationInfo表示是否打印位置信息，即日志事件发生的代码文件名、代码行号，log4j配置文件中需要配置为LocationInfo

title输出html文档head的title部分，默认为Log4J Log Messages，log4j配置文件中需要配置为Title

XMLLayout继承自Layout的方法实现有：

//默认返回”text/html”
public String getContentType()
//配置加载完成后操作，实现为空
public void activateOptions()
//返回相应HTML头部部分，具体是html、head、title以及body、table的开始部分
public String getHeader()
//返回相应html尾部，具体是table、body、html的html闭合标签
public String getFooter()
//返回false，即由HTMLLayout本身处理异常信息格式化，HTMLLayout有成员函数appendThrowableAsHTML，具体是将Throwable对应的字符串做相关转移和替换处理，以符合html语法
public boolean ignoresThrowable()
//具体序列化LoggingEvent为字符串
public String format(LoggingEvent event)
3.1 format实现

a. 缓冲StringBuffer更新，判断容量是否超过HTMLLayout的MAX_CAPACITY(1024)，如果超过则创建新的StringBuffer，否则复用原有的StringBuffer，避免内存浪费，具体和XMLLayout原理一致。
b. 输出时间、线程、Level等上下文信息，根据locationInfo（如果locationInfo为true）、Level等具体字符串拼接和格式化

0
main
INFO
com.luohw.log4j.LayoutTest
LayoutTest.java:12
info:123

c. 输出NDC信息

NDC: ndc message

d. 如果有则输出异常栈信息，一般Logger的日志函数info、warn、error等都有带Throwable型参的重载
e. 没有MDC相关信息的格式化输出

3.2 demo

demo java code:

Logger logger = Logger.getLogger(LayoutTest.class);
NDC.push(“ndc message”);
logger.info(“info:123”);
logger.warn(“warn:abc”);
logger.error(“error:xyz”);
logger.info(“exception”, new RuntimeException(“run time exception”));
demo log4j config:

log4j.rootLogger=INFO,Console
log4j.appender.Console=org.apache.log4j.ConsoleAppender
log4j.appender.Console.target=System.out
log4j.appender.Console.layout=org.apache.log4j.HTMLLayout
log4j.appender.Console.layout.LocationInfo=true
log4j.appender.Console.layout.Title=luohw@log4j

demo浏览器打开日志输出html:

html