log4j的2.6.2版本properties配置文件的使用舉例

【寫作動機】

　　log4j是由apache基金會開發的開源日誌組件，是用來記錄日誌文件的一套API，截止發文當天（2016/09/28）的最新版爲v2.6.2版。與傳統1.2版相比，新版log4j在properties配置文件的具體使用上解釋不多，網上相關資料也很少。下面結合示例略作說明，希望起到理清思路、拋磚引玉的作用。

【官網文檔參考】

　　配置log4j的2.x版可以通過以下4中方式實現：

（1）通過xml格式、json格式、yaml格式或properties格式的配置文件的方式；
（2）通過編程，創建ConfigurationFactory和實現Configuration接口的方式；
（3）通過編程，調用Configuration接口現成的各類API來向默認配置方式添加其他部件的方式；
（4）通過編程，調用內部Logger類方法的方式。

　　這裏重點介紹properties格式的配置文件在使用時的注意事項。

　　log4j組件2.4以後的版本已經能夠支持.properties格式的配置文件（之前的2.x版均不支持.properties配置），只是語法結構上與1.2版有所不同。新版properties格式配置文件與其他格式（XML格式、JSON格式文件等）一樣，配置的主要任務是完成對各類插件及其屬性的定義。

　　在2.6版之前——
　　　（1）properties配置文件需要在首行列出定義的各類輸出源（appenders）、過濾器（filters）及記錄器（loggers）的名稱，並以逗號隔開，其後又需要按需要定義的組件與名稱聯繫起來，以鍵值對【某屬性=某值】的方式，成組地定義具體的屬性值。
　　　（2）值得注意的是，名稱並不需要逐一成組地指定屬性值，但必須保證下面列出的所有屬性及屬性值具有唯一性。如果沒有列出由逗號分隔的一組定義名稱，那麼這些名稱中就不能出現半角英文句點符號'.'。
　　　（3）此外，每一個獨立的組件必須包含一個特定的type屬性，以指明該組件對應的插件類型（Plugin type）。

　　從2.6版開始，這樣的定義名稱列表不再強制列出，因爲名稱通常可以在首次使用時推斷出來。但如果確實需要定義更復雜的名稱，建議還是使用名稱列表。列表一旦列出便會生效。

　　與基礎部分的配置不同，在創建子部件時，不能在某個元素上指定一系列名稱，而必須像下面舉例說明的RollingFileAppender那樣，在定義其多個策略（policies）的值時，必須先定義一個policies屬性對應的包裝元素（wrapper element）：appender.rolling.policies.type = Policies，然後再在它下面定義兩個子部件（TimeBasedTriggeringPolicy和SizeBasedTriggeringPolicy）各具體屬性的值。

　　此外，properties配置文件還支持如下屬性：advertiser、monitorInterval、name、packages、shutdownHook、status和verbose。

官方示例：RollingFileAppender的properties示例配置文件如下：

status = error
name = PropertiesConfig
 
property.filename = target/rolling/rollingtest.log
 
filter.threshold.type = ThresholdFilter
filter.threshold.level = debug
 
appender.console.type = Console
appender.console.name = STDOUT
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = %m%n
 
appender.rolling.type = RollingFile
appender.rolling.name = RollingFile
appender.rolling.fileName = ${filename}
appender.rolling.filePattern = target/rolling2/test1-%d{MM-dd-yy-HH-mm-ss}-%i.log.gz
appender.rolling.layout.type = PatternLayout
appender.rolling.layout.pattern = %d %p %C{1.} [%t] %m%n
appender.rolling.policies.type = Policies
appender.rolling.policies.time.type = TimeBasedTriggeringPolicy
appender.rolling.policies.time.interval = 2
appender.rolling.policies.time.modulate = true
appender.rolling.policies.size.type = SizeBasedTriggeringPolicy
appender.rolling.policies.size.size=100MB
appender.rolling.strategy.type = DefaultRolloverStrategy
appender.rolling.strategy.max = 5
 
appender.list.type = List
appender.list.name = List
appender.list.filter.threshold.type = ThresholdFilter
appender.list.filter.threshold.level = error
 
logger.rolling.name = com.example.my.app
logger.rolling.level = debug
logger.rolling.additivity = false
logger.rolling.appenderRef.rolling.ref = RollingFile
 
rootLogger.level = info
rootLogger.appenderRef.stdout.ref = STDOUT

　　由於缺乏更詳細的說明，也不能與RollingFileAppender的xml格式配置文件作對比，上述properties格式內容理解起來難度較大。爲便於比較，先列出1.2版常規的properties配置文件，文件名爲log4j.properties，要求根日誌級別爲debug，配置兩個輸出目的地，一個到控制檯，級別爲debug，一個到日誌文件，級別爲error，文件完整路徑爲e:\propertiesTest.log：

　　1.2版log4j.properties文件代碼如下：

log4j.rootLogger=debug,a,b

log4j.appender.a=org.apache.log4j.ConsoleAppender
log4j.appender.a.Threshold=debug
log4j.appender.a.target=System.out
log4j.appender.a.layout=org.apache.log4j.PatternLayout
log4j.appender.a.layout.ConversionPattern=%m%n

log4j.appender.b=org.apache.log4j.FileAppender
log4j.appender.b.Threshold=error
log4j.appender.b.ImmediateFlush=true
log4j.appender.b.File=e:\\propertiesTest.log
log4j.appender.b.Append=true
log4j.appender.b.layout=org.apache.log4j.PatternLayout
log4j.appender.b.layout.ConversionPattern=%d -%m%n

　　最新的log4j2.properties文件代碼如下：

status = warn
name = MyApp

appender.console.type = Console
appender.console.name = consoleLogDemo
appender.console.filter.threshold.type = ThresholdFilter
appender.console.filter.threshold.level = debug
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = %m%n
appender.console.target = System_out

appender.rolling.type = File
appender.rolling.name = fileLogDemo
appender.rolling.filter.threshold.type = ThresholdFilter
appender.rolling.filter.threshold.level = error
appender.rolling.layout.type = PatternLayout
appender.rolling.layout.pattern = %d-%m%n
appender.rolling.append = true
appender.rolling.fileName = e:\\propertiesTest.log

rootLogger.level = debug
rootLogger.appenderRef.consolelogdemo.ref = consoleLogDemo
rootLogger.appenderRef.filelogdemo.ref = fileLogDemo

　　與之對比的log4j2.xml文件如下：

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE xml>
<Configuration status="warn" name="MyApp">
	<appenders>
		<Console name="consoleLogDemo" target="SYSTEM_OUT">
			<ThresholdFilter level="debug"/>
			<PatternLayout pattern="%m%n" />
		</Console>
		
		<File name="fileLogDemo" fileName="e:\\propertiesTest.log" append="true">
			<ThresholdFilter level="error" />
			<PatternLayout pattern="%d-%m%n" />
		</File>
	</appenders>
	     
	<loggers>
		<root level="debug">
			<appender-ref ref="consoleLogDemo"></appender-ref>
			<appender-ref ref="fileLogDemo"></appender-ref>
		</root>
	</loggers>
</Configuration>

對比新舊版本的properties文件，可以有如下結論：

（1）舊版第一行定義根日誌級別與輸出目標的名稱語句被轉述到下方，聲明語句也更突顯結構性，用了上文中提到的包裝元素：

rootLogger.level = debug
rootLogger.appenderRef.consolelogdemo.ref = consoleLogDemo
rootLogger.appenderRef.filelogdemo.ref = fileLogDemo
其中第一句是指定根日誌的級別，爲debug；第2、3句是在上一句包裝元素的統領下，指定哪些appender輸出源是默認執行根日誌的輸出級別。要用到的屬性是appender的name值。注意左邊的name是全部小寫，右邊才和定義的name完全一樣。如果漏寫第3句，則控制檯上將不顯示File類型的日誌記錄。

（2）新版本直接用appender.console.type和appender.console.name指定輸出源的類型爲Console，指定的名稱爲consoleLogDemo（不固定）。之所以省去原版首行的定義名稱列表，可能是從字面上也能推斷出要使用的是Console類型的appender吧。

（3）原來對console輸出級別作控制的log4j.appender.a.threshold=debug變成了先聲明type，再指定level的形式，結構性比原來更明顯了，有點“先聲明後使用”的感覺：
appender.console.filter.threshold.type = ThresholdFilter
appender.console.filter.threshold.level = debug

（4）layout佈局屬性也是這樣，先聲明type類型（對應原來的log4j.appender.a.layout=org.apache.log4j.PatternLayout），再指定日誌記錄樣式pattern的值（對應原來的log4j.appender.a.layout.ConversionPattern=%m%n），新版本看起來更工整：
appender.console.layout.type = PatternLayout 
appender.console.layout.pattern = %m%n

（5）另外一個細節是，原版console屬性target的值要麼是System.err，要麼是System.out，前者日誌信息顯示爲紅色，後者爲黑色，且只有這兩種屬性值。在新版中，屬性值的功能和個數不變，但寫法上要把英文句點符號"."改爲下劃線"_"。

【其他準備工作】

使用log4j，原版需要導入log4j-1.2.17.jar包，到某項目的WebContent/WEB-INF/lib目錄下。新版本v2.6.2版同之前的2.x各類版本一樣，導入目錄不變，但需要導入兩個新版jar包：

log4j-api-2.6.2.jar
log4j-core-2.6.2.jar

配置文件方面，不論是log4j2.xml還是log4j2.properties，都需要複製到src根目錄下（如下圖所示）

【具體使用】

只需要定義一個Logger類型的實例，用LogManager.getLogger(String name);語句具體創建。

示例代碼如下：

package javastudy;

import org.apache.logging.log4j.Level;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

public class HelloLog4j2 {
	public static Logger log4j2Demo = LogManager.getLogger(HelloLog4j2.class.getName());
	
	public static void main(String[] arg0) {
		log4j2Demo.trace("Demo1:我是trace信息，通過.trace(Sting s1)生成。");
		log4j2Demo.debug("Demo2:我是debug信息，通過.debug(String s2)生成。");
		log4j2Demo.info("Demo3:我是info信息，通過.info(String s3)生成。");
		log4j2Demo.warn("Demo4:我是warn信息，通過.warn(String s4)生成。");
		log4j2Demo.error("Demo5:我是error信息，通過.error(String s5)生成。");
		log4j2Demo.fatal("Demo6:我是fatal信息，通過.fatal(String s6)生成。");
		System.out.println();
		/*Valid Levels include: 
		 * (ALL <) TRACE < DEBUG < INFO < WARN < ERROR < FATAL (< OFF)*/
		log4j2Demo.log(Level.DEBUG, "Demo7:我是debug信息，通過.log(Level.DEBUG,String s7)生成。");
		log4j2Demo.log(Level.ERROR, "Demo8:我是error信息，通過.log(Level.ERROR,String s8)生成。");	
	}
}

運行結果：

日誌文件生成情況：

日誌文件內容：

　　從結果中可知，由於根日誌規定顯示的最低級別爲debug，因此trace級別的Demo1無法顯示。日誌級別按重要性遞增的方式可分爲8個級別，常用的是中間6個級別：
(ALL <) TRACE < DEBUG < INFO < WARN < ERROR < FATAL (< OFF)

　　因此，只需要在上文的log4j2.xml文件中（注意文件名末尾有個2，與1.2版不同），把<root level="debug">改爲<root level="trace">，即可在控制檯看到示例列出的所有級別的日誌信息，但日誌文件propertiesTest.log由於規定只允許error及以上級別的記錄，因此文件內容保持不變。

參考資料：

http://logging.apache.org/log4j/2.x/manual/configuration.html
http://blog.csdn.net/lrenjun/article/details/8178875
http://www.cnblogs.com/hanfight/p/5721855.html
http://www.cnblogs.com/leo-lsw/p/log4j2tutorial.html
http://blog.csdn.net/lu8000/article/details/25754415
http://zengxiantao.iteye.com/blog/1881700