Log4j 設定檔完整指南：屬性配置與最佳實踐

Log4j 設定檔概述

Log4j 的設定檔（通常命名為 log4j.properties）是控制日誌記錄行為的核心。它採用鍵值對（key=value）或 XML 格式定義記錄器層級、輸出目的地以及日誌輸出格式。透過適當配置，即可建立符合專案需求的 Log4j 執行環境。

基本結構與核心元素

1. 根記錄器配置

根記錄器是所有日誌記錄器的祖先，其語法為：

log4j.rootLogger = [level], appenderName1, appenderName2, ...

level 定義日誌輸出等級，共五級（由高到低）：

• FATAL (0)
• ERROR (3)
• WARN (4)
• INFO (6)
• DEBUG (7)

2. Appender（輸出目的地）

Appender 決定日誌輸出去向，常見類型包括：

• org.apache.log4j.ConsoleAppender - 控制台輸出
• org.apache.log4j.FileAppender - 檔案輸出
• org.apache.log4j.DailyRollingFileAppender - 每日產生新檔案
• org.apache.log4j.RollingFileAppender - 檔案達指定大小時滾動
• org.apache.log4j.WriterAppender - 以流形式發送至指定位置

3. Layout（輸出格式）

Layout 定義日誌訊息的顯示格式：

• org.apache.log4j.HTMLLayout - HTML 表格形式
• org.apache.log4j.PatternLayout - 靈活指定模式（最常用）
• org.apache.log4j.SimpleLayout - 包含等級與訊息字串
• org.apache.log4j.TTCCLayout - 包含時間、執行緒、類別等資訊

PatternLayout 常用轉換字元

程式碼中初始化 Logger 的四種方式

1. BasicConfigurator.configure()：為根記錄器新增 ConsoleAppender，格式為 "%-4r [%t] %-5p %c %x - %m%n"，預設等級 DEBUG。
2. PropertyConfigurator.configure(args[x])：透過命令列參數傳遞設定檔路徑。
3. 環境變數：利用 Log4j 預設初始化流程讀取環境變數指定的設定檔。
4. 應用伺服器 Servlet：透過特殊 Servlet 在應用伺服器啟動時載入設定。

進階配置技巧

為不同 Appender 設定不同輸出等級

利用 Threshold 參數可讓特定 Appender 只記錄特定等級以上的日誌。例如：將錯誤日誌單獨寫入 error.log，一般日誌寫入 log.log：

log4j.rootLogger = debug, stdout, D, E

# 控制台輸出
log4j.appender.stdout = org.apache.log4j.ConsoleAppender
log4j.appender.stdout.Target = System.out
log4j.appender.stdout.layout = org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern = %d{ABSOLUTE} %5p %c{1}:%L - %m%n

# 一般日誌檔（每日滾動）
log4j.appender.D = org.apache.log4j.DailyRollingFileAppender
log4j.appender.D.File = logs/log.log
log4j.appender.D.Append = true
log4j.appender.D.Threshold = DEBUG
log4j.appender.D.layout = org.apache.log4j.PatternLayout
log4j.appender.D.layout.ConversionPattern = %-d{yyyy-MM-dd HH:mm:ss} [%t:%r] - [%p] %m%n

# 錯誤日誌檔（僅 ERROR 以上）
log4j.appender.E = org.apache.log4j.DailyRollingFileAppender
log4j.appender.E.File = logs/error.log
log4j.appender.E.Append = true
log4j.appender.E.Threshold = ERROR
log4j.appender.E.layout = org.apache.log4j.PatternLayout
log4j.appender.E.layout.ConversionPattern = %-d{yyyy-MM-dd HH:mm:ss} [%t:%r] - [%p] %m%n

針對特定套件設定不同日誌等級

可透過 log4j.logger.<packageName>=level 覆寫特定套件的日誌等級，例如：

log4j.logger.org.springframework.orm.hibernate3.support.OpenSessionInViewFilter=debug
log4j.logger.org.apache.struts.util=WARN

原理：Log4j 會優先匹配最精確的記錄器名稱，若無設定則繼承父層級設定。

完整範例：log4j.properties

# 根記錄器：DEBUG 等級，輸出至控制台與檔案
log4j.rootLogger=DEBUG,myConsole,myLogFile

# 控制台 Appender
log4j.appender.myConsole=org.apache.log4j.ConsoleAppender
log4j.appender.myConsole.layout=org.apache.log4j.PatternLayout
log4j.appender.myConsole.layout.ConversionPattern=%5p [%t] (%F:%L) - %m%n
log4j.appender.myConsole.threshold=FATAL

# 滾動檔案 Appender
log4j.appender.myLogFile=org.apache.log4j.RollingFileAppender
log4j.appender.myLogFile.File=mylog.log
log4j.appender.myLogFile.MaxFileSize=100KB
log4j.appender.myLogFile.MaxBackupIndex=2
log4j.appender.myLogFile.layout=org.apache.log4j.PatternLayout
log4j.appender.myLogFile.layout.ConversionPattern=%d{MMM d,yyyy hh:mm:ss a} : %p [%t] %m%n
log4j.appender.myLogFile.threshold=ERROR

最佳實踐建議

• 生產環境建議將根等級設為 INFO 或 WARN，避免過多 DEBUG 輸出影響效能。
• 使用 RollingFileAppender 或 DailyRollingFileAppender 防止單一檔案過大。
• 善用 Threshold 將錯誤日誌隔離，利於快速排查問題。
• 對第三方套件（如 Spring、Struts）單獨設定等級，減少雜訊。
• 格式建議包含時間、執行緒、類名、行號，便於追蹤。