Log4j 2.x 完整配置指南：從入門到生產級調優

Apache Log4j 2 是新一代高效能日誌框架，支援非同步記錄、自動重載、豐富的 Appender 與 Layout。本文涵蓋配置文件結構、核心組件、Spring 整合、Web 容器初始化、分包級別控制與生產環境調優參數。

配置文件格式選擇

• XML：功能最完整，支援所有特性（如 ScriptFilter、JDBCAppender 複雜參數）。
• JSON/YAML：結構清晰，適合配置中心下發。
• Properties：精簡，僅支援基礎屬性，不支援非同步 Logger、自定義 Plugin 等進階功能。生產環境建議用 XML/JSON。

核心配置結構 (log4j2.xml)

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" monitorInterval="30">  <!-- 自動重載間隔秒 -->
  <Properties>
    <Property name="LOG_PATTERN">%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n</Property>
    <Property name="LOG_DIR">${sys:catalina.base}/logs</Property>
  </Properties>

  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <PatternLayout pattern="${LOG_PATTERN}"/>
    </Console>

    <RollingFile name="RollingFile" fileName="${LOG_DIR}/app.log"
                 filePattern="${LOG_DIR}/app-%d{yyyy-MM-dd}.log.gz">
      <PatternLayout pattern="${LOG_PATTERN}"/>
      <Policies>
        <TimeBasedTriggeringPolicy interval="1" modulate="true"/>  <!-- 每日滾動 -->
        <SizeBasedTriggeringPolicy size="100 MB"/>                <!-- 或達 100MB 滾動 -->
      </Policies>
      <DefaultRolloverStrategy max="30"/>  <!-- 保留 30 檔 -->
    </RollingFile>

    <Async name="AsyncFile">  <!-- 非同步包裝，提升吞吐 -->
      <AppenderRef ref="RollingFile"/>
    </Async>
  </Appenders>

  <Loggers>
    <Root level="INFO">
      <AppenderRef ref="Console"/>
      <AppenderRef ref="AsyncFile"/>
    </Root>

    <Logger name="com.example.business" level="DEBUG" additivity="false">
      <AppenderRef ref="AsyncFile"/>
    </Logger>

    <Logger name="org.springframework" level="WARN"/>
    <Logger name="org.hibernate.SQL" level="DEBUG"/>
  </Loggers>
</Configuration>

關鍵組件說明

Spring Boot 整合（零配置啟動）

1. 引入 spring-boot-starter-log4j2（自動排除 Logback）。
2. 將 log4j2.xml 放在 src/main/resources。
3. application.yml 可覆寫路徑：logging.config: classpath:log4j2-prod.xml。

傳統 Web 容器初始化（非 Spring）

<!-- web.xml -->
<context-param>
  <param-name>log4jConfiguration</param-name>
  <param-value>/WEB-INF/log4j2.xml</param-value>
</context-param>
<listener>
  <listener-class>org.apache.logging.log4j.web.Log4jServletContextListener</listener-class>
</listener>
<filter>
  <filter-name>log4jServletFilter</filter-name>
  <filter-class>org.apache.logging.log4j.web.Log4jServletFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>log4jServletFilter</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>FORWARD</dispatcher>
  <dispatcher>INCLUDE</dispatcher>
  <dispatcher>ERROR</dispatcher>
</filter-mapping>

生產環境調優參數

常見坑點避雷

• 重複日誌： 子 Logger additivity="false" 避免向 Root 傳遞導致雙倍輸出。
• 類載入器洩漏： 容器重部署時關閉 LogManager：LogManager.shutdown()（ServletContextListener 執行）。
• 非同步丟失日誌： JVM 關閉前呼叫 LogManager.shutdown() 刷緩衝區；或設 shutdownHook="disable" 自行管理。
• MDC 透傳： 非同步模式下 MDC 需配合 includeMdc="true" (AsyncAppender) 或使用 ThreadContext。

遷移自 Log4j 1.x 注意事項

1. 包名變更：org.apache.log4j → org.apache.logging.log4j。
2. API 分離：log4j-api (介面) + log4j-core (實作)。
3. PropertyConfigurator 棄用，改用 Configurator.initialize() 或依賴自動發現。
4. DailyRollingFileAppender → RollingFile + TimeBasedTriggeringPolicy。

善用 Log4j 2 的非同步架構與豐富生態，能在高併發系統中實現「低延遲、高吞吐、可運維」的日誌觀測能力。