日志框架（二）Log4j XML配置详解

原创已于 2025-10-16 09:59:27 修改 · 1k 阅读

28 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

中间件

工具

于 2025-10-14 10:27:07 首次发布

低功耗蓝牙项目，需要一块懂省电的板

思澈 SF32LB52 芯片，BLE 协议栈深度优化，上手即开发

点击查看

一、Log4j2 XML 配置文件结构

Log4j2 的 XML 配置文件通常命名为 log4j2.xml，放在 resources 或 classpath 根目录下。基本结构如下：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" monitorInterval="30">
    <Properties>
        <Property name="logPath">logs</Property>
    </Properties>
    <Appenders>
        <!-- 定义日志输出目标 -->
    </Appenders>
    <Loggers>
        <!-- 定义日志器、分级和关联输出目标 -->
    </Loggers>
</Configuration>

二、主要元素详解

1. `<Configuration>`

根元素，包含所有配置内容。
常用属性：
- status：控制 Log4j2 本身的内部日志级别（如 ERROR, WARN, INFO），用于调试配置问题。
- monitorInterval：单位秒，配置文件变更后自动热加载的检测周期。

2. `<Properties>`

定义全局属性变量，可在后续配置中通过 ${} 引用。

示例：

<Properties>
    <Property name="logPath">logs</Property>
</Properties>

3. `<Appenders>`

定义所有日志输出目标（Appender），每个 Appender 可独立配置。
常见类型：
- Console：控制台输出
- File：普通文件输出
- RollingFile：自动切割的文件输出
- JDBC：数据库输出
- Async：异步输出
- 自定义插件 Appender

Console 示例

<Console name="Console" target="SYSTEM_OUT">
    <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss} [%t] %-5level %logger{36} - %msg%n"/>
</Console>

RollingFile 示例

<RollingFile name="RollingFile"
             fileName="${logPath}/app.log"
             filePattern="${logPath}/app-%d{yyyy-MM-dd}-%i.log.gz">
    <PatternLayout pattern="%d %p %c [%t] %m%n"/>
    <Policies>
        <TimeBasedTriggeringPolicy interval="1"/>
        <SizeBasedTriggeringPolicy size="100 MB"/>
    </Policies>
    <DefaultRolloverStrategy max="10"/>
</RollingFile>

fileName：当前日志文件路径
filePattern：切割后日志文件命名规则
Policies：切割策略（按时间、按大小）
DefaultRolloverStrategy：归档文件最大保留数量

Async 示例

<Async name="AsyncAppender">
    <AppenderRef ref="Console"/>
    <AppenderRef ref="RollingFile"/>
</Async>

4. `<Loggers>`

定义所有日志器（Logger），包括根日志器和自定义命名日志器。
支持分级、继承、单独配置输出目标。

Root Logger（根日志器）

<Root level="info">
    <AppenderRef ref="Console"/>
    <AppenderRef ref="RollingFile"/>
</Root>

level：日志级别（ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF）
AppenderRef：关联输出目标

命名 Logger

<Logger name="com.example" level="debug" additivity="false">
    <AppenderRef ref="RollingFile"/>
</Logger>

name：包名或类名，支持通配
level：该 Logger 的日志级别
additivity：是否向上级 Logger 传递日志（false 只用本 Logger 的 Appender）

5. `<Filters>`

可以在 Appender、Logger 或全局配置下定义过滤器，控制日志输出条件。

<Console name="Console">
    <PatternLayout pattern="..."/>
    <Filters>
        <ThresholdFilter level="WARN" onMatch="ACCEPT" onMismatch="DENY"/>
    </Filters>
</Console>

三、常用高级配置说明

1. 日志变量引用

在 <Properties> 中定义变量后，可通过 ${变量名} 在任何配置项中引用。

2. 日志格式 PatternLayout

占位符丰富：%d（时间）、%p（级别）、%c（Logger）、%t（线程）、%m（消息）、%n（换行）等。

示例：

<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>

3. 文件切割与归档策略

TimeBasedTriggeringPolicy：按时间切割
SizeBasedTriggeringPolicy：按文件大小切割
DefaultRolloverStrategy：归档文件最大数量

4. 异步日志

推荐高并发场景下使用 <Async> Appender 或 <AsyncLogger>，显著提升性能。

5. 日志分级与继承

Logger 支持分级（如 com.example、com.example.service），子 Logger 默认继承父 Logger 配置，除非 additivity="false"。

四、完整配置实例

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" monitorInterval="60">
    <Properties>
        <Property name="logPath">logs</Property>
    </Properties>
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss} [%t] %-5level %logger{36} - %msg%n"/>
        </Console>
        <RollingFile name="RollingFile"
                     fileName="${logPath}/app.log"
                     filePattern="${logPath}/app-%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout pattern="%d %p %c [%t] %m%n"/>
            <Policies>
                <TimeBasedTriggeringPolicy interval="1"/>
                <SizeBasedTriggeringPolicy size="50 MB"/>
            </Policies>
            <DefaultRolloverStrategy max="5"/>
        </RollingFile>
        <Async name="AsyncAppender">
            <AppenderRef ref="Console"/>
            <AppenderRef ref="RollingFile"/>
        </Async>
    </Appenders>
    <Loggers>
        <Logger name="com.example" level="debug" additivity="false">
            <AppenderRef ref="AsyncAppender"/>
        </Logger>
        <Root level="info">
            <AppenderRef ref="AsyncAppender"/>
        </Root>
    </Loggers>
</Configuration>

五、实用技巧与常见问题

配置文件热加载：monitorInterval 属性自动检测配置变更，单位秒。
多环境配置：可通过不同配置文件或变量实现开发/测试/生产环境日志策略切换。
日志归档和清理：合理设置归档数量和切割策略，避免磁盘空间占满。
性能优化：高吞吐场景下建议使用异步日志。
调试 Log4j2 本身：通过 status="DEBUG" 输出详细日志，定位配置错误。

六、常用 Appender 配置详解

1. ConsoleAppender（控制台输出）

<Console name="Console" target="SYSTEM_OUT">
    <PatternLayout pattern="%d{HH:mm:ss} [%t] %-5level %logger{36} - %msg%n"/>
</Console>

target 可选 SYSTEM_OUT 或 SYSTEM_ERR
适合开发环境实时查看日志

2. FileAppender（普通文件）

<File name="FileLog" fileName="logs/app.log">
    <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss} %-5level %c - %m%n"/>
</File>

日志文件不会自动切割，适合小型或临时日志

3. RollingFileAppender（自动切割文件）

<RollingFile name="RollingFile"
             fileName="logs/app.log"
             filePattern="logs/app-%d{yyyy-MM-dd}-%i.log.gz">
    <PatternLayout pattern="%d %p %c [%t] %m%n"/>
    <Policies>
        <TimeBasedTriggeringPolicy interval="1"/>
        <SizeBasedTriggeringPolicy size="50 MB"/>
    </Policies>
    <DefaultRolloverStrategy max="10"/>
</RollingFile>

支持按天、按大小切割
归档文件自动压缩（.gz）

4. JDBCAppender（数据库日志）

<JDBC name="DatabaseAppender" tableName="logs" columnConfigs="...">
    <ConnectionFactory class="com.example.MyConnectionFactory"/>
    <PatternLayout pattern="%d %p %c [%t] %m%n"/>
</JDBC>

需实现 ConnectionFactory
适合审计、安全等场景

5. SMTPAppender（邮件报警）

<SMTP name="MailAppender"
      subject="Log4j2 Alert"
      to="admin@example.com"
      from="log@example.com"
      smtpHost="smtp.example.com"
      smtpPort="25">
    <PatternLayout pattern="%d %p %c - %m%n"/>
    <Filter type="ThresholdFilter" level="ERROR"/>
</SMTP>

适合异常报警、关键事件通知

6. AsyncAppender（异步输出）

<Async name="AsyncAppender">
    <AppenderRef ref="Console"/>
    <AppenderRef ref="RollingFile"/>
</Async>

提升高并发性能
推荐将所有主要 Appender 包裹在 Async 中

七、常用 Filter 配置详解

1. ThresholdFilter（按级别过滤）

<ThresholdFilter level="WARN" onMatch="ACCEPT" onMismatch="DENY"/>

只输出指定级别及以上的日志

2. RegexFilter（正则匹配过滤）

<RegexFilter regex=".*关键字.*" onMatch="ACCEPT" onMismatch="DENY"/>

只输出包含“关键字”的日志

3. MarkerFilter（按 Marker 标签过滤）

<MarkerFilter marker="SECURITY" onMatch="ACCEPT" onMismatch="DENY"/>

只输出打了特定 Marker 的日志

4. CompositeFilter（多条件组合过滤）

<Filters>
    <ThresholdFilter level="ERROR" onMatch="ACCEPT" onMismatch="DENY"/>
    <RegexFilter regex=".*报警.*" onMatch="ACCEPT" onMismatch="DENY"/>
</Filters>

满足任一条件即可输出

八、PatternLayout 占位符详解

占位符	含义
%d{格式}	日志时间
%p	日志级别
%c{长度}	Logger 名（可截取）
%t	线程名
%m	日志消息
%n	换行
%F	源文件名
%L	行号
%M	方法名
%X{key}	MDC（上下文变量）
%logger{36}	Logger 名，最长36字符

示例：

<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} (%F:%L) - %msg%n"/>

九、分环境配置技巧

1. 使用变量和占位符

<Properties>
    <Property name="env">dev</Property>
    <Property name="logPath">logs/${env}</Property>
</Properties>

2. 多配置文件切换

log4j2-dev.xml、log4j2-prod.xml
启动参数指定：-Dlog4j.configurationFile=log4j2-prod.xml

3. 使用条件 Appender

<Logger name="com.example" level="debug">
    <AppenderRef ref="${env == 'prod' ? 'RollingFile' : 'Console'}"/>
</Logger>

（部分功能需 Log4j2 2.13+）

十、异步日志配置与优化

1. 全局异步 Logger

<Configuration>
    <AsyncLogger name="com.example" level="info">
        <AppenderRef ref="RollingFile"/>
    </AsyncLogger>
</Configuration>

适合高并发写日志场景
异步 Logger 比 AsyncAppender 性能更高

2. 异步参数优化

<Async name="AsyncAppender" bufferSize="10240" blocking="false">
    <AppenderRef ref="RollingFile"/>
</Async>

bufferSize：队列大小
blocking：队列满时是否阻塞主线程

十一、常见问题与排查方法

日志不输出？
- 检查 Logger/Appender/Filter 的级别设置
- 检查是否引用了正确的 Appender
- 配置文件是否被正确加载（可加 status=“DEBUG”）
日志重复输出？
- 检查 Logger 的 additivity 属性，非必要时设为 false
- 检查 Appender 是否被多次引用
归档文件过多？
- DefaultRolloverStrategy 的 max 属性正确设置
配置修改未生效？
- 检查 monitorInterval 是否配置，或重启应用
性能低下？
- 推荐开启异步日志，合理设置 bufferSize