1. 项目概述：为什么Log4j配置依然是开发者的必修课

最近在帮团队排查一个线上服务性能抖动的问题，最后定位到日志组件上。一个看似简单的日志异步化配置没做好，在高并发场景下直接成了性能瓶颈。这让我再次意识到，尽管Log4j（无论是经典的1.x还是功能强大的2.x）已经是一个“老伙计”了，但它的配置远不是把jar包扔进classpath、写两行log.info那么简单。很多开发者，尤其是刚入行的朋友，往往只满足于“能打出日志”，却忽略了如何“打好日志”——这直接关系到线上问题的排查效率、系统的可观测性以及在高负载下的稳定性。

“Log4j 1.x和2.x的配置示例”这个标题，听起来像是一份基础的API文档，但它的内核远不止于此。它关乎的是一套完整的日志治理策略：如何根据环境（开发/生产）动态调整日志级别？如何设计滚动策略，避免日志文件撑爆磁盘？如何将不同业务模块的日志分离，便于定向分析？以及，在微服务架构下，如何配置才能与现有的监控、链路追踪体系无缝集成？今天，我就结合自己踩过的坑和积累的经验，把Log4j两代版本的核心配置逻辑、升级注意事项以及那些官方手册里不会写的“实战技巧”一次性讲透。无论你是在维护一个历史悠久的基于Log4j 1.x的系统，还是在全新项目中拥抱Log4j 2.x，这篇文章都能给你提供可直接“抄作业”的配置模板和深度避坑指南。

2. 核心差异与选型：1.x的经典与2.x的革新

在动手写配置之前，我们必须先理清Log4j 1.x和2.x的根本性区别。这不仅仅是版本号的变化，而是架构设计上的代际革新。盲目地从1.x照搬到2.x，或者在不了解差异的情况下混用，都会埋下隐患。

2.1 架构与性能的鸿沟

Log4j 1.x在其诞生时代是划时代的产物，但其核心架构存在一些历史局限性。最突出的问题是同步日志记录。默认情况下，当你的应用调用logger.info(“message”)时，当前线程会阻塞，直到这条日志被完全写入到目的地（比如控制台或文件）。在低流量时这没什么感觉，但在高并发场景下，大量的I/O等待会严重拖慢应用响应速度。虽然1.x后期也提供了AsyncAppender来实现异步，但它是基于阻塞队列的，设计上并非原生，且在极端情况下（如队列满）可能导致日志丢失或阻塞。

Log4j 2.x则从根上重构了。它采用了**无锁异步日志（Asynchronous Loggers）**作为其高性能的核心。其异步实现基于高性能并发库LMAX Disruptor，实现了真正的非阻塞。这意味着日志记录事件被放入环形缓冲区后，调用线程立即返回，由后台线程负责实际的I/O操作。根据官方测试，在多线程环境下，Log4j 2.x的异步日志性能可以比Log4j 1.x和Logback高出数倍甚至一个数量级。

另一个关键差异是配置重载。Log4j 1.x在启动后，配置基本上是静态的。如果你想修改日志级别，通常需要重启应用。而Log4j 2.x支持自动扫描并重载配置文件（如monitorInterval属性），这对于需要动态调整日志级别来排查线上问题的运维场景来说，是巨大的便利。

2.2 API与配置文件的兼容性与断裂

在API层面，Log4j 2.x提供了两个API门面：org.apache.logging.log4j.LogManager和传统的org.apache.log4j.Logger（桥接API）。为了平滑升级，它允许你使用旧的log4j-1.2-api桥接包，让那些调用org.apache.log4j.Logger的老代码在Log4j 2.x核心上运行。但这只是一个兼容层，你无法使用2.x的新特性。

配置文件格式的差异就更明显了：

• Log4j 1.x：通常使用log4j.properties（属性文件格式）或log4j.xml。其语法相对简单直接。
• Log4j 2.x：支持log4j2.xml、log4j2.json、log4j2.yaml以及log4j2.properties。其中，log4j2.xml功能最强大，也是社区最常用的格式。它的语法结构更清晰、更强大，支持条件化配置、脚本支持等高级功能。

注意：这里有一个经典的“坑”。如果你在项目中同时存在log4j-1.2.x.jar和log4j-core-2.x.jar，并且没有正确配置桥接，很可能会遇到类加载冲突或者日志完全不输出的情况。正确的做法是，如果升级到2.x，就移除所有1.x的jar包，并通过桥接包来兼容老代码。

2.3 选型建议：什么时候该用谁？

• 坚持使用Log4j 1.x的场景：

  • 维护一个非常古老且稳定、近期无改造计划的应用。
  • 应用本身极其简单，日志量很小，性能不是瓶颈。
  • 团队对1.x的配置非常熟悉，且没有动态调整日志的需求。
  • 但需要严重警告：Log4j 1.x版本已停止维护多年，已知存在一些无法修复的缺陷和安全风险（尽管不如Log4Shell影响大）。从技术债和安全性角度，长期来看升级是必选项。

• 毫不犹豫选择Log4j 2.x的场景：

  • 所有新建项目。这是目前Java生态下性能最强、功能最丰富的日志框架之一。
  • 对应用性能有较高要求，特别是高并发、高吞吐量的服务。
  • 需要灵活的、支持热重载的日志配置。
  • 希望利用更丰富的过滤器（Filter）、查找器（Lookup）等高级功能来定制日志行为。

我个人在实际项目中的体会是：除非有不可抗拒的历史原因，否则新项目和技术改造项目一律采用Log4j 2.x。其性能收益和运维便利性带来的价值，远远超过学习新配置格式的成本。接下来，我们就深入两者的配置腹地。

3. Log4j 1.x 配置详解与经典模式

虽然Log4j 1.x已渐行渐远，但理解它的配置有助于我们更好地处理遗留系统，也能在对比中更深刻地理解2.x的改进。我们以最常用的log4j.properties格式为例。

3.1 核心三要素：Logger, Appender, Layout

这是Log4j（包括2.x）配置的基石思维模型，一定要建立起来：

1. Logger（记录器）：这是你代码中直接打交道的对象。它负责捕获日志事件。Logger是有层次结构的（通常按包名），子Logger会继承父Logger的配置。
2. Appender（输出源）：定义日志输出的目的地。比如控制台（ConsoleAppender）、文件（FileAppender）、滚动文件（RollingFileAppender）、数据库（JDBCAppender）等。
3. Layout（布局）：定义每条日志输出内容的格式。比如是否包含时间、线程、日志级别、类名等信息。

一个简单的log4j.properties示例如下：

# 1. 设置根Logger的级别和Appender log4j.rootLogger=INFO, stdout, file # 2. 配置控制台Appender 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{yyyy-MM-dd HH:mm:ss} [%t] %-5p %c{1}:%L - %m%n # 3. 配置滚动文件Appender log4j.appender.file=org.apache.log4j.RollingFileAppender log4j.appender.file.File=/var/log/myapp/app.log log4j.appender.file.MaxFileSize=100MB log4j.appender.file.MaxBackupIndex=10 log4j.appender.file.layout=org.apache.log4j.PatternLayout log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} [%t] %-5p %c{1}:%L - %m%n # 4. 为特定包设置更详细的日志级别（继承并覆盖根配置） log4j.logger.com.mycompany.myproject.service=DEBUG log4j.logger.org.springframework=WARN

配置解析与实操要点：

• rootLogger：INFO, stdout, file表示根日志级别为INFO，并同时输出到名为stdout和file的两个Appender。多个Appender用逗号分隔。
• PatternLayout：这是最灵活的布局。ConversionPattern中的占位符是关键：
  • %d：日期时间。{yyyy-MM-dd HH:mm:ss}指定格式，{ISO8601}是标准格式。
  • %t：线程名。
  • %p：日志级别（INFO, DEBUG等），-5表示左对齐并占5个字符宽度。
  • %c：Logger名称（通常是类名），{1}表示只输出最后一部分（类名），省略包路径。
  • %L：输出日志的行号。这是一个需要特别注意的地方：获取行号（%L）需要编译器在编译时生成行号表（默认是生成的），但这会带来微小的性能开销。在生产环境下，如果对性能有极致要求，可以考虑去掉%L。
  • %m：日志消息本身。
  • %n：平台相关的换行符。
• RollingFileAppender：MaxFileSize和MaxBackupIndex定义了滚动策略。当app.log达到100MB时，会被重命名为app.log.1，原来的app.log.1变成app.log.2，以此类推，最多保留10个备份文件。更旧的会被删除。

3.2 高级配置：异步日志与按天滚动

对于1.x，要实现更好的性能和归档，我们通常会组合使用AsyncAppender和DailyRollingFileAppender。

# 配置一个按天滚动的文件Appender log4j.appender.dailyFile=org.apache.log4j.DailyRollingFileAppender log4j.appender.dailyFile.File=/var/log/myapp/app.log log4j.appender.dailyFile.DatePattern='.'yyyy-MM-dd log4j.appender.dailyFile.layout=org.apache.log4j.PatternLayout log4j.appender.dailyFile.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p [%t] %c{2} - %m%n # 配置一个异步Appender，并引用上面的dailyFile作为其底层Appender log4j.appender.async=org.apache.log4j.AsyncAppender log4j.appender.async.BufferSize=512 log4j.appender.async.Blocking=false log4j.appender.async.appender-ref=dailyFile # 根Logger使用异步Appender log4j.rootLogger=INFO, async

注意事项：

• AsyncAppender.Blocking：默认为true，即当内部队列满时，调用线程会阻塞。设为false时，队列满则丢弃日志（通常是级别较低的日志），适合对性能要求极高且允许少量日志丢失的场景。生产环境一般建议设为true，保证日志完整性。
• BufferSize：队列大小。需要根据应用的日志吞吐量来调整。太小容易阻塞或丢日志，太大则占用更多内存。512或1024是常见的起步值。
• DailyRollingFileAppender有一个著名的“坑”：它只在每次日志事件发生时检查是否需要滚动。如果应用在午夜时段没有产生任何日志，那么滚动就不会发生，导致日志继续写入前一天的文件。对于严格按天归档的需求，这可能是个问题。社区有各种补丁或自定义Appender来解决，但在2.x中，这个问题被更强大的滚动策略彻底解决了。

4. Log4j 2.x 配置进阶与性能调优

来到Log4j 2.x，配置的思维模型基本不变，但能力和表达方式有了质的飞跃。我们以功能最全的log4j2.xml为例。

4.1 基础配置结构与模式解析

一个标准的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 %c{1.} - %msg%n</Property> <Property name="LOG_PATH">/var/log/myapp</Property> <Property name="APP_NAME">my-application</Property> </Properties> <Appenders> <!-- 在这里定义各种输出源 --> </Appenders> <Loggers> <!-- 在这里定义Logger及其级别、Appender引用 --> <Root level="info"> <AppenderRef ref="Console"/> <AppenderRef ref="RollingFile"/> </Root> </Loggers> </Configuration>

关键属性解析：

• status：Log4j 2内部日志的级别，可选TRACE,DEBUG,INFO,WARN,ERROR,FATAL。在排查配置问题时，可以设为TRACE或DEBUG，会在控制台打印详细的加载过程。生产环境务必设为WARN或ERROR，避免刷屏。
• monitorInterval：单位是秒。设为30表示Log4j 2会每30秒检查一次配置文件是否有变化，如有则自动重载。这是2.x的王牌功能之一，极大方便运维。
• <Properties>：定义属性，可以在后续配置中通过${propertyName}引用，使配置更清晰、易于维护。

4.2 核心Appender配置实战

4.2.1 控制台与基本文件输出

<Appenders> <!-- 1. 彩色控制台输出 (非常实用) --> <Console name="Console" target="SYSTEM_OUT"> <PatternLayout pattern="${LOG_PATTERN}" disableAnsi="false"/> <!-- 或者使用更丰富的带颜色的布局 --> <!-- <PatternLayout pattern="%style{%d{ISO8601}}{black} %highlight{%-5level} [%style{%t}{bright,blue}] %style{%c{1.}}{cyan}: %msg%n"/> --> </Console> <!-- 2. 基本文件输出 --> <File name="File" fileName="${LOG_PATH}/${APP_NAME}.log"> <PatternLayout pattern="${LOG_PATTERN}"/> </File> </Appenders>

在开发环境，使用带颜色的控制台输出（%highlight）能极大提升日志可读性。disableAnsi="false"确保颜色转义码生效。

4.2.2 强大的滚动文件策略（RollingFile）

这是生产环境的标配，功能比1.x强大得多。

<RollingFile name="RollingFile" fileName="${LOG_PATH}/${APP_NAME}.log" filePattern="${LOG_PATH}/archive/${APP_NAME}-%d{yyyy-MM-dd}-%i.log.gz"> <PatternLayout pattern="${LOG_PATTERN}"/> <Policies> <!-- 基于时间的滚动策略：每天滚动一次 --> <TimeBasedTriggeringPolicy interval="1" modulate="true"/> <!-- 基于文件大小的滚动策略：单个文件超过100MB则滚动 --> <SizeBasedTriggeringPolicy size="100 MB"/> </Policies> <!-- 默认滚动策略，与上面的Policies配合 --> <DefaultRolloverStrategy max="30" compressionLevel="9"> <Delete basePath="${LOG_PATH}/archive" maxDepth="2"> <IfFileName glob="${APP_NAME}-*.log.gz" /> <IfLastModified age="30d" /> </Delete> </DefaultRolloverStrategy> </RollingFile>

配置深度解析：

• filePattern：定义了滚动后文件的命名规则。%d{yyyy-MM-dd}表示按日期，%i是一个递增索引（当同一天内因文件大小触发多次滚动时使用）。.gz后缀表示自动用GZIP压缩归档文件，这是一个强烈推荐的做法，能节省大量磁盘空间。
• Policies：滚动触发策略。可以同时配置时间和大小策略，满足任一条件即触发滚动。modulate="true"会让滚动时间对齐到0点（例如从启动时间算间隔1天，调整为每天0点滚动），让日志归档更规整。
• DefaultRolloverStrategy：滚动覆盖策略。max=”30″表示最多保留30个归档文件（不是30天）。更强大的是嵌套的<Delete>元素，它定义了自动清理策略：
  • basePath：在哪个目录下执行删除。
  • maxDepth：扫描子目录的深度。
  • <IfFileName>：匹配哪些文件（支持通配符）。
  • <IfLastModified>：文件最后修改时间早于age=”30d”（30天）。
  • 这个组合意味着：它会自动删除archive目录下，匹配模式且超过30天的压缩日志文件。这彻底解决了需要借助外部cron job来清理日志的麻烦，是生产环境必备配置。

4.2.3 异步日志配置（性能关键）

Log4j 2的异步分为两种：Async Appender和Async Logger。后者性能更好，是推荐方式。

方式一：使用Async Appender（与1.x思路类似）

<Appenders> <RollingFile name="RollingFileSync" ...> ... </RollingFile> <Async name="Async" bufferSize="1024" blocking="true"> <AppenderRef ref="RollingFileSync"/> </Async> </Appenders> <Loggers> <Root level="info"> <AppenderRef ref="Async"/> </Root> </Loggers>

方式二：使用Async Logger（全局异步，推荐）这需要在类路径上添加disruptor-3.4.x.jar依赖，并在配置中或系统属性中指定。

• 配置方式：在log4j2.xml的<Configuration>标签或<Loggers>标签上添加status=”async”。
• 更推荐的方式：在JVM启动参数中设置-Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector。这会将所有Logger设置为异步。

性能调优心得：

• bufferSize：对于Async Appender或Async Logger的环形缓冲区大小。默认是1024（条日志事件）。对于日志量巨大的应用，可以适当调大到4096或8192，但会增加内存开销和故障时潜在的数据丢失量。
• blocking：队列满时的行为。true为阻塞，false为丢弃。生产环境为了数据完整性，通常选true。
• 实测建议：对于绝大多数Web应用和服务，使用全局异步Logger（Async Logger）并配合合理的滚动和清理策略，日志性能几乎可以忽略不计。我曾在一个QPS过万的系统中对比过，同步日志导致TP99上升了约15ms，改为异步后，日志带来的延迟几乎测不出来了。

4.3 Logger的精细化管理与过滤

Log4j 2.x的Logger配置更灵活，支持叠加（Additivity）和直接引用Appender。

<Loggers> <!-- 根Logger --> <Root level="INFO"> <AppenderRef ref="Console"/> <AppenderRef ref="RollingFile"/> </Root> <!-- 特定包/类Logger：设置更低的级别，用于调试 --> <Logger name="com.mycompany.myproject.service" level="DEBUG" additivity="false"> <AppenderRef ref="Console"/> <!-- 仅调试时输出到控制台，方便查看 --> </Logger> <!-- 特定包/类Logger：设置更高的级别，减少噪音 --> <Logger name="org.apache.kafka" level="WARN"/> <Logger name="org.springframework" level="WARN"/> <!-- 将某个模块的日志分离到独立文件 --> <Logger name="com.mycompany.myproject.access" level="INFO" additivity="false"> <AppenderRef ref="AccessFile"/> <!-- 需要额外定义一个RollingFile，filePattern指向access.log --> </Logger> </Loggers>

关键点：

• additivity=”false”：这是非常重要的属性。默认为true，表示该Logger的日志事件在传递给自身配置的Appender后，还会继续传递给祖先Logger（直到Root）的Appender。这经常导致日志被重复打印。当你为某个Logger指定了独立的Appender时，通常需要设置additivity=”false”，以避免日志既出现在独立文件，又出现在Root Logger的总日志文件中。
• 日志分离实践：像访问日志（Access Log）、审计日志、特定业务模块的日志，通过配置独立的Logger和Appender，将其输出到单独的文件。这样在排查问题时，可以直接tail -f access.log，而不被其他业务日志干扰，大大提升效率。

5. 从1.x迁移到2.x的实操指南与避坑大全

如果你负责将一个使用Log4j 1.x的老系统升级到2.x，以下步骤和注意事项至关重要。

5.1 迁移步骤

1. 依赖调整：

   • 移除所有Log4j 1.x的依赖（如log4j:log4j:1.2.17）。
   • 添加Log4j 2.x核心依赖：

     <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> <version>2.17.2</version> <!-- 请使用最新的稳定版本 --> </dependency>

   • 添加Log4j 2.x API依赖（如果代码中用到了SLF4J，则加这个）：

     <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-api</artifactId> <version>2.17.2</version> </dependency>

   • 如果老代码直接使用org.apache.log4j.Logger，必须添加桥接依赖，否则会报ClassNotFoundException：

     <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-1.2-api</artifactId> <version>2.17.2</version> </dependency>

   • （可选但推荐）如果需要异步日志，添加Disruptor依赖：

     <dependency> <groupId>com.lmax</groupId> <artifactId>disruptor</artifactId> <version>3.4.4</version> </dependency>

2. 配置文件转换：

   • 将原有的log4j.properties或log4j.xml转换为log4j2.xml或log4j2.properties。Apache官网提供了转换工具，但手动重写往往更可靠，因为可以借此机会优化配置（如引入自动清理策略）。
   • 重要：确保配置文件命名为log4j2.xml并放在类路径根目录（如src/main/resources下）。Log4j 2不会识别log4j.xml。

3. 代码层面检查：

   • 如果使用了桥接包，理论上直接调用org.apache.log4j.Logger.getLogger()的代码无需修改。
   • 但如果想使用Log4j 2的新API，可以逐步将代码改为使用org.apache.logging.log4j.LogManager.getLogger()。
   • 检查是否有直接操作Log4j 1.x内部类（如自定义Appender）的代码，这部分需要重写为Log4j 2的插件体系。

5.2 常见问题与排查技巧实录

问题1：迁移后日志完全不输出。

• 排查：
  1. 首先检查status=”TRACE”，查看控制台内部日志，确认配置文件是否被加载，有无错误。
  2. 检查依赖冲突。确保没有其他日志框架（如logback-classic,slf4j-log4j12）的jar包在类路径上，它们可能会“劫持”日志门面。使用mvn dependency:tree或检查lib目录。
  3. 确认配置文件名称和位置正确（log4j2.xml在类路径根目录）。

问题2：日志重复打印。

• 原因：几乎都是因为Logger的additivity属性没设对。
• 解决：检查所有非Root Logger，如果为其指定了专属Appender，且你不想让该日志也出现在Root的Appender里，务必加上additivity=”false”。

问题3：异步日志配置后，应用关闭时部分日志丢失。

• 原因：JVM关闭时，异步日志线程可能被强制中断，缓冲区中的日志事件来不及写入。
• 解决：
  1. 注册一个JVM关闭钩子（Shutdown Hook），在钩子中手动调用LogManager.shutdown()。Log4j 2提供了ShutdownCallbackRegistry。
  2. 或者，在配置中为<AsyncLogger>或<AsyncRoot>设置shutdownTimeout=”30000″（单位毫秒），指定一个关闭超时时间，让框架有机会刷出缓冲区日志。

问题4：按天滚动的日志，在午夜后没有立即生成新文件。

• 原因：在Log4j 2.x中，TimeBasedTriggeringPolicy的滚动检查是惰性的，通常在下次日志事件到达时触发。如果午夜后一段时间没有日志，滚动会延迟。
• 解决：可以搭配使用CronTriggeringPolicy来实现精确到秒的定时滚动。或者，对于严格要求的场景，可以编写一个定时任务，在午夜时发送一条无关紧要的日志（如logger.debug(“Rolling trigger”)）来“唤醒”滚动检查。

问题5：日志文件增长过快，磁盘空间报警。

• 排查：
  1. 首先检查日志级别是否为DEBUG或TRACE。生产环境除了特定调试期，Root Logger应为INFO或WARN。
  2. 检查是否有第三方库在疯狂打印日志。通过配置为这些库（如org.apache,com.zaxxer.hikari等）设置更高的级别（WARN）。
  3. 优化PatternLayout，去掉不必要的信息（如行号%L、方法名%M），它们会增加输出体积。
  4. 最关键的一步：确保配置了合理的滚动策略和自动删除策略（即前面提到的<Delete>标签）。这是防止磁盘撑爆的终极保障。

一份实用的日志级别设置参考表：

配置日志从来不是一劳永逸的事情，它需要随着应用的发展、部署环境的变化而不断调整和优化。最好的习惯是，在项目初期就建立一套标准化的、包含滚动和清理的配置模板，并在每次发布前，像检查代码一样检查日志配置是否与环境匹配。毕竟，清晰、完整、高效的日志，是你在深夜排查线上问题时，最值得信赖的“灯塔”。