Apache Log4j 2.26.1 介绍与核心概念详解

目标：理解 Apache Log4j 2.26.1 的架构分层与核心对象模型，能据此设计应用的日志方案并正确选型。文中结论与回显均来自 Ubuntu 22.04（OpenJDK 17）实测。

一、环境信息

表后逐项说明：Log4j 自 2.24.0 起要求 Java 17 运行时，2.26.1 延续该要求，与 Ubuntu 22.04 的 openjdk-17-jdk-headless 完全匹配；核心构件只有 log4j-api 与 log4j-core 两个 jar，异步日志额外需要 disruptor。

二、概述

Apache Log4j 2 是 Apache Logging Services 项目的旗舰日志框架，log4j-core 2.26.1 于 2026 年发布，是 2.x 系列的当前稳定版。它由两部分构成：

• log4j-api：面向应用编程的接口层（Logger、Level、Marker、ThreadContext 等），只定义 API 不含实现，供业务代码与应用类库依赖。
• log4j-core：默认实现层（LoggerContext、Appender、Layout、Filter 的全部实现），运行时必须与 api 同时在 classpath。

实测依赖解析（mvn dependency:tree 输出）：

[INFO] com.example:log4j-demo:jar:1.0.0
[INFO] +- org.apache.logging.log4j:log4j-api:jar:2.26.1:compile
[INFO] +- org.apache.logging.log4j:log4j-core:jar:2.26.1:compile
[INFO] \- com.lmax:disruptor:jar:4.0.0:compile

说明：api 与 core 没有传递依赖链，需要各自显式声明（core 依赖 api 的老版本约定已在新版本中明确），disruptor 是异步日志器（AsyncLogger）的环形缓冲实现。

💡 技术拓展：日志布局的两大流派——文本布局（PatternLayout 用正则式占位符拼人读文本）与结构化布局（JsonTemplateLayout/GelfLayout 输出机器可解析 JSON，面向 ELK/Loki 采集）。本文实验以 PatternLayout 为主、控制台与滚动文件为载体；接入集中式日志平台时建议在生产配置模板基础上把 File Appender 的布局换成 JsonTemplateLayout。

三、核心架构

3.1 分层模型

表后逐项说明：一次 log.info() 调用依次经过 Logger 级别检查 → Logger 关联 Filter → 各 Appender 的 Filter → Layout 格式化 → Appender 输出；任何一层拒绝即终止。

3.2 核心对象详解

Logger（日志器）

• 以类名或自定义名从 LogManager.getLogger 取得，按点分层级（com.example 是 com.example.demo 的父级）。
• 每个.Logger 有级别（Level），级别检查规则：当前事件级别 >= Logger 级别才继续（TRACE 0 到 OFF 2147483647，实际可用六级 TRACE/DEBUG/INFO/WARN/ERROR/FATAL）。
• additivity 属性决定事件是否继续向父 Logger 的 Appender 传播，默认 true（常见"日志打两遍"的根源，实测见第 6.2 节）。

Appender（输出器）

• Console：输出到 stdout/stderr，开发期最常用。
• File：固定文件名。
• RollingFile：按时间/大小滚动归档，配 Policies 与 RolloverStrategy。
• 其他内建：JDBC、JPA、Kafka、Socket、Syslog、Memory 等。

Layout（布局）

• PatternLayout：占位符 %d/%p/%c/%t/%m/%X/%marker 等拼格式（本文实测主角）。
• JsonTemplateLayout：JSON 结构化输出，接入 ELK/Loki。

Filter（过滤器）

• ThresholdFilter：放行 >= 指定级别（本文实测：DEBUG 阈值拦掉 TRACE）。
• LevelMatchFilter：只放行指定级别（2.26 中的名字，旧版本叫 LevelFilter，实测第 6.3 节）。
• MarkerFilter、RegexFilter、TimeFilter、BurstFilter 等。

Level（级别）

• 标准六级严重度递增：TRACE < DEBUG < INFO < WARN < ERROR < FATAL。
• 本文实测同一 Logger 的七种调用在 Root=INFO 与 com.example=DEBUG 下的输出差异（TRACE 被过滤）。

Marker（标记）

• 命名标签，支持父子继承。本文实测 AUDIT 继承 SECURITY 后，输出中显示 AUDIT[ SECURITY ]。

ThreadContext（线程上下文，旧称 MDC）

• 以键值对往日志注入请求维度信息。本文实测 ThreadContext.put("requestId", "req-20260101-0001") 后，pattern 中 %X{requestId} 输出 req-20260101-0001。

3.3 配置发现顺序

log4j-core 启动时按以下顺序定位配置（以 -Dlog4j.configurationFile 直接指定为最高优先级，本文实验全部采用该方式）：

1. 系统属性 log4j.configurationFile 指定的文件；
2. classpath 下的 log4j2.properties / log4j2.yaml / log4j2.json / log4j2.xml（先找 log4j2-test.*）；
3. 全部找不到时使用默认配置：仅一个 ERROR 级别的 Console，输出到 stderr。

默认配置实测（把配置文件清空导致解析失败后，框架回退默认配置的 stderr 输出）：

2026-10-14T17:26:08.467875664Z main ERROR Error parsing /opt/log4j-demo/src/main/resources/log4j2-levelfilter.xml
org.xml.sax.SAXParseException; systemId: file:///opt/log4j-demo/src/main/resources/log4j2-levelfilter.xml; lineNumber: 1; columnNumber: 1; Premature end of file.

2026-10-14T17:25:45.849488420Z main ERROR error 级别消息，订单 1001 支付超时

逐项说明：配置不可用时应用并不抛异常退出，而是静默回退到"只打 ERROR 及以上、ISO8601 时间戳、输出到 stderr"的默认配置，这也是"日志突然变奇怪"最常见的原因，排查时先确认配置文件被正确加载。

四、功能特性

• 高性能异步日志：AsyncLogger 基于 LMAX Disruptor 环形缓冲，业务线程入队即返回。实测 50 万条 INFO 日志提交耗时 5383 ms，LogManager.shutdown 后完整落盘 500000 行。
• 插件化架构：Configuration/Appender/Layout/Filter 全部是插件，status 调到 DEBUG 可见插件扫描（实测 PluginManager 'Core' found 134 plugins）。
• 多格式配置：XML/JSON/YAML/Properties 四种配置格式等价，支持 monitorInterval 热更新。
• 无垃圾（garbage-free）模式：稳态日志路径避免临时对象，降低 GC 压力。
• 延迟求值与 lambda：logger.debug("值是 " + obj) 写法无论级别是否输出都会拼串，而 logger.debug("值是 {}", () -> expensive()) 仅在确定输出时求值。
• 级别继承树：Logger 层级继承父级级别，只需在包级别设一次。
• 上下文注入：ThreadContext 键值对 + %X 占位符，天然适配链路追踪 requestId/traceId。

五、适用场景与选型对比

5.1 适用场景

• 传统 Web 服务/微服务：Console + RollingFile 组合，PatternLayout 文本日志。
• 高并发网关/交易系统：AsyncLogger + includeLocation=false，压榨吞吐。
• 集中式日志采集：JsonTemplateLayout 输出 JSON，Filebeat/Promtail 采集。
• 类库与框架：仅依赖 log4j-api，把实现选择权交给上层应用。

5.2 同类框架对比

表后逐项说明：追求吞吐与低延迟选 Log4j 2 的 AsyncLogger（Disruptor 比 BlockingQueue 方案有量级优势）；Spring Boot 新项目可用默认 Logback，但 SLF4J 门面下可无痛切 Log4j 2；JUL 只在无法加依赖的场景使用；Log4j 1.x 已停止维护且存在已知漏洞，存量项目应迁移到 2.x。

💡 技术拓展：门面还是直接用？SLF4J/JCL 是"门面"（只有接口），Log4j 2/Logback 是"实现"。业务代码建议面向门面写（slf4j-api + log4j-slf4j2-impl 桥接），便于日后换实现；但 SLF4J 的 MDC 在 Log4j 2 里对应 ThreadContext，Marker 语义也有细微差异，深度使用 Marker/自定义 Level 时直接用 log4j-api 更顺。本文实验直接依赖 log4j-api。

六、核心概念实测验证

6.1 级别过滤与 Throwable 输出

测试配置（Console + ThresholdFilter level=DEBUG + PatternLayout）：

<Configuration status="WARN" monitorInterval="30">
  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} [%marker] [req=%X{requestId}] - %msg%n%throwable"/>
      <ThresholdFilter level="DEBUG" onMatch="ACCEPT" onMismatch="DENY"/>
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="com.example" level="DEBUG" additivity="false">
      <AppenderRef ref="Console"/>
    </Logger>
    <Root level="INFO">
      <AppenderRef ref="Console"/>
    </Root>
  </Loggers>
</Configuration>

逐项说明：Logger com.example 级别 DEBUG 且 additivity=false，Root 级别 INFO 兜底其他类；Appender 上 ThresholdFilter 防御性拦截 TRACE。

运行输出（实测）：

2026-10-14 16:57:03.122 [main] DEBUG com.example.LevelConsoleDemo [] [req=req-20260101-0001] - debug 级别消息，SQL 参数预览
2026-10-14 16:57:03.126 [main] INFO  com.example.LevelConsoleDemo [] [req=req-20260101-0001] - info 级别消息，服务启动完成
2026-10-14 16:57:03.126 [main] WARN  com.example.LevelConsoleDemo [] [req=req-20260101-0001] - warn 级别消息，磁盘使用率 85%
2026-10-14 16:57:03.127 [main] ERROR com.example.LevelConsoleDemo [] [req=req-20260101-0001] - error 级别消息，订单 1001 支付超时
java.lang.IllegalStateException: payment timeout
        at com.example.LevelConsoleDemo.main(LevelConsoleDemo.java:20)
2026-10-14 16:57:03.128 [main] FATAL com.example.LevelConsoleDemo [] [req=req-20260101-0001] - fatal 级别消息，无法连接数据库
2026-10-14 16:57:03.128 [main] INFO  com.example.LevelConsoleDemo [AUDIT[ SECURITY ]] [req=req-20260101-0001] - 用户 root 登录成功（AUDIT 继承自 SECURITY）

逐项说明：trace 级别消息被三层机制拦下（Logger DEBUG 级别 < TRACE 需求端、ThresholdFilter DEBUG 阈值）；ERROR 行后跟完整异常栈（%throwable 与 log.error(msg, throwable) 参数配合）；Marker 列 AUDIT[ SECURITY ] 展示父子 Marker 继承；每行末尾 req= 值来自 ThreadContext。

6.2 additivity 传播实测

把 Logger 的 additivity 去掉（默认 true）后，同一条 info 日志输出了两遍（Logger 自身 AppenderRef 一遍、向 Root 传播再打一遍）：

ADD-TEST 17:24:52.840 [main] INFO  com.example.LevelConsoleDemo - info 级别消息，服务启动完成
ADD-TEST 17:24:52.840 [main] INFO  com.example.LevelConsoleDemo - info 级别消息，服务启动完成

结论：显式配置了 AppenderRef 的 Logger 建议一律 additivity="false"，除非确实需要多 Appender 叠加。

6.3 精确级别过滤实测

2.26.1 中精确匹配级别的是 LevelMatchFilter（旧名 LevelFilter 已不存在，误用会报错）：

2026-10-14T17:25:23.040714088Z main ERROR Console contains an invalid element or attribute "LevelFilter"

改用 LevelMatchFilter level="WARN" onMatch="ACCEPT" onMismatch="DENY" 后，Root=DEBUG 的程序只输出 WARN 一行：

LEVELFILTER WARN  - warn 级别消息，磁盘使用率 85%

6.4 内部状态日志实测

Configuration 的 status 属性调到 DEBUG 可看到框架装配过程（节选）：

2026-10-14T17:26:30.661243734Z main DEBUG Apache Log4j Core 2.26 initializing configuration XmlConfiguration[location=/opt/log4j-demo/src/main/resources/log4j2-debug.xml, lastModified=2026-10-14T17:25:02.014Z]
2026-10-14T17:26:30.663621510Z main DEBUG PluginManager 'Core' found 134 plugins
2026-10-14T17:26:30.663827778Z main DEBUG PluginManager 'Level' found 0 plugins
2026-10-14T17:26:30.678042838Z main DEBUG PluginManager 'Lookup' found 15 plugins

说明：status 日志与业务日志相互独立（status 描述 log4j 自身），排查"配置没生效/插件找不到"问题时把它调成 DEBUG 是第一手段。

七、常见问题（FAQ）

Q1：log4j-api 和 log4j-core 为什么都要引入？ A：api 是编译期接口，core 是运行期实现。只引 api 时 LoggerContext 找不到实现，所有日志走"无实现"空转（输出 ERROR 级别默认配置或完全静默），实测依赖树里两者都是 compile 级 compile scope 缺一不可。

Q2：为什么我的日志打了两次？ A：Logger 的 additivity 默认为 true，自身 AppenderRef 输出一遍后又向 Root 传播一遍。实测把 com.example 的 AppenderRef 去掉 additivity 后同一行出现两次 ADD-TEST 前缀。解决：子 Logger 显式 additivity="false"。

Q3：配置文件改了没生效？ A：三步排查：确认启动参数 -Dlog4j.configurationFile 指向的是修改后的文件（或文件在 classpath 且打包更新）；确认 monitorInterval（默认 0 表示不热更新，需显式设置如 30 秒）；把 status 调成 DEBUG 看初始化输出的 XmlConfiguration[location=...] 是不是目标文件。

Q4：LevelFilter 报 Console contains an invalid element or attribute "LevelFilter"？ A：2.26.1 中该插件名为 LevelMatchFilter，LevelFilter 已被移除。实测错误回显为 Console contains an invalid element or attribute "LevelFilter"，替换为 LevelMatchFilter 后立即正常（只输出 WARN 级别）。

Q5：trace 日志怎么都不输出？ A：TRACE 是最低级别，会被 Logger 级别（低于 Logger 级别的事件不产生）与 ThresholdFilter（level=DEBUG 时 onMismatch=DENY）双重拦截。临时排查时把目标 Logger 级别设为 TRACE 并移除或调低 ThresholdFilter。

Q6：程序没配置 log4j 时为什么还会打出 ERROR 日志？ A：这是默认配置（DefaultConfiguration）行为：解析不到配置时回退为 ERROR 级别、输出到 stderr、ISO8601 时间戳格式（实测回显 2026-10-14T17:25:45.849488420Z main ERROR ...）。看到这种格式就该检查配置文件加载了没有。

Q7：异步日志需要什么额外依赖？ A：AsyncLogger 需要 com.lmax:disruptor（实测 2.26.1 配 4.0.0 正常）。缺 disruptor 时异步 Logger 无法创建，日志退回同步路径，吞吐优势消失。

Q8：Log4j 2 为什么要求 Java 17？ A：从 2.24.0 起核心模块基线提升到 Java 17，以使用更新的语言与 JVM 特性并收紧维护面。2.17~2.23 是最后支持 Java 8 的版本。Ubuntu 22.04 用 openjdk-17-jdk-headless 即满足（实测 17.0.20.1）。

Q9：Marker 与 Level 的区别？什么时候用 Marker？ A：Level 表达"严重程度"，Marker 表达"业务标签"，两者正交。Marker 用于审计/安全等需要独立开关与路由的日志类别，本文实测 AUDIT 继承 SECURITY 后 MarkerFilter 可按 AUDIT 或 SECURITY 任一名匹配；MarkerFilter 不受 Level 影响。

Q10：log4j 1.x 的应用怎么迁移？ A：代码里 org.apache.log4j.Logger 改为 org.apache.logging.log4j.Logger（或经 log4j-1.2-api 桥接零改码）；log4j.properties 重写为 log4j2.xml（Appender/Logger 语法不同，参数见本专栏配置详解篇）；务必同时下线旧 jar，避免双框架并存。

八、参考链接

1. Apache Log4j 官方文档：https://logging.apache.org/log4j/2.x/
2. Log4j 2.26.1 Maven Central（log4j-api）：https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-api/2.26.1/
3. Log4j 2.26.1 Maven Central（log4j-core）：https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.26.1/
4. Log4j 架构说明（Architecture 页）：https://logging.apache.org/log4j/2.x/manual/architecture.html
5. LMAX Disruptor：https://lmax-exchange.github.io/disruptor/
6. SLF4J 与 Log4j 桥接（log4j-slf4j2-impl）：https://logging.apache.org/log4j/2.x/log4j-slf4j2-impl/