把日志写进文件或控制台，本质是一次 I/O 操作。同步记录模式下，业务线程必须等日志框架完成写入才能继续执行；一旦磁盘抖动或控制台输出滞后，接口耗时就会被拉长。Log4j2 针对这个问题提供了异步日志能力，核心思路是引入有界队列或无锁环形缓冲区，让业务线程只负责投递事件，由后台消费者独立完成真正的写入。CodeGeex 可以在提交注释或局部代码后自动生成 Log4j2 相关配置，下面从异步实现原理开始梳理。
一、Log4j2 异步日志的两种实现方式与底层原理
Log4j2 的异步日志并不只有一种形态，它主要分为 AsyncAppender 和 AsyncLogger 两类。AsyncAppender 是在 Appender 层做异步包装，内部维护一个阻塞队列和后台写线程，适合只需要让某个或某几个 Appender 异步的场景。而 AsyncLogger 则直接在 Logger 层走 Disruptor 环形缓冲区，如果开启全异步模式，项目里所有 Logger 的日志事件都会先进入无锁队列，再由消费者线程批量写入目标 Appender。
全异步模式需要设置系统属性或配置文件中的 Log4jContextSelector 为 org.apache.logging.log4j.core.async.AsyncLoggerContextSelector，同时引入 LMAX Disruptor 依赖。Disruptor 使用环形缓冲区、无锁并发和缓存行填充来减少多线程竞争，适合单生产者或多生产者下的高吞吐写入。AsyncLogger 的优势在于日志事件在 Logger 层就被投递，省去了再封装一层 AsyncAppender 队列的开销。
相比之下，AsyncAppender 的配置更直观，可以精确控制哪些 Appender 异步，但它的队列在业务线程与后台线程之间多了一次事件传递；如果 queueSize 设置不当，容易出现队列满导致阻塞或丢弃事件。全异步模式对代码侵入较小，只需要引入 disruptor 并开启选择器即可，但要注意异常堆栈的定位信息可能带来额外性能开销。两者可以单独使用，不建议在全异步模式下再叠加 AsyncAppender，否则相当于双重队列，浪费资源。
开启全异步最基本的配置文件如下，通常放在 classpath 根目录下的 log4j2.component.properties 中：
# 开启 Log4j2 全异步模式 Log4jContextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector
二、利用 CodeGeex 生成基础异步配置
CodeGeex 支持在 IDE 内通过注释触发补全，也可以直接使用对话方式描述需求。例如在工程里新建一个空白的 log4j2.xml 文件，写下这样一行注释：“生成 Log4j2 全异步配置，包含 Console 和 RollingFile，日志级别 info，保留 20 个滚动文件”，然后触发 CodeGeex 补全，通常能直接得到 XML 配置骨架以及对应的 Maven 依赖片段。
生成结果一般需要重点检查几个地方：disruptor 版本是否与 Log4j2 版本兼容；是否在配置中保留了必要的 log4j2.component.properties 或 JVM 系统属性；文件路径和滚动策略是否符合当前项目目录结构。下面是一段由 CodeGeex 生成后整理过的 Maven 依赖示例：
<dependencies>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
<version>2.20.0</version>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-api</artifactId>
<version>2.20.0</version>
</dependency>
<dependency>
<groupId>com.lmax</groupId>
<artifactId>disruptor</artifactId>
<version>3.4.4</version>
</dependency>
</dependencies>
如果只想让特定 Appender 异步，而不希望全项目都走 Disruptor，也可以让 CodeGeex 生成 AsyncAppender 配置。例如提示“使用 AsyncAppender 包装 RollingFile，队列大小 2048，队列满时阻塞写入”，它会给出一个包装结构的 XML 片段。生成后再核对 <AppenderRef> 是否指向了异步 Appender 而不是原始 Appender，否则日志仍然会同步写盘。
使用 CodeGeex 的过程中，最好先写清楚目标日志目录、保留天数和单文件上限。这些约束会直接影响生成的 RollingFile 策略，避免后续手工调整。对于全异步模式，生成器有时不会自动补 log4j2.component.properties，需要在项目根目录的 resources 下补齐，否则配置不会生效。
三、线程池与队列参数调优
全异步日志的队列本质上是 Disruptor 的环形缓冲区，可以通过系统属性调整容量和等待策略。常用参数包括 log4j2.AsyncLoggerRingBufferSize、log4j2.AsyncLoggerWaitStrategy 以及 log4j2.AsyncQueueFullPolicy。环形缓冲区大小必须是 2 的幂，默认值可以满足大多数场景，但如果单机日志量很大，可以调大到 32768 或更高，同时注意内存占用会随之增加。
AsyncLoggerWaitStrategy 决定消费者线程如何等待新事件，可选值包括 Block、Timeout、Sleep、Yield 等。Block 策略在空闲时会阻塞线程，CPU 占用低但唤醒延迟稍高；Timeout 会等待一段时间后自旋，适合对延迟敏感但可以牺牲 CPU 的场景。队列满时的策略通常用 Discard，表示丢弃新事件，避免阻塞业务线程；也可以选择默认策略，让业务线程短暂等待。
如果使用 AsyncAppender，则需要关注 XML 中的 queueSize、blocking 和 shutdownTimeout。其中 blocking=true 表示队列满时阻塞业务线程直到有空位，保证日志不丢但会拖慢调用；blocking=false 则直接丢弃新事件，适合允许少量丢失的监控类日志。shutdownTimeout 控制应用关闭时等待后台线程处理剩余日志的毫秒数，设置过小可能导致最后几条日志未落盘。
全异步模式的参数可以在 log4j2.component.properties 中配置：
# 调整全异步日志的环形缓冲区大小和等待策略 log4j2.AsyncLoggerRingBufferSize=32768 log4j2.AsyncLoggerWaitStrategy=Block log4j2.AsyncQueueFullPolicy=Discard
如果是 AsyncAppender，则需要修改 XML 片段：
<Async name="AsyncRolling" blocking="false" queueSize="4096" shutdownTimeout="2000"> <AppenderRef ref="RollingFile"/> </Async>
这两个方案不要混用，否则全异步已经让 Logger 事件进入 Disruptor，再经过 AsyncAppender 的阻塞队列，只会增加延迟和内存消耗。调优时建议先用简单压测观察吞吐和 CPU，再决定是否提高 RingBufferSize 或更换 WaitStrategy。对于日志输出为控制台的情况，Console Appender 往往比文件写入更慢，必要时可以把控制台日志关闭或改到异步输出。
四、完整配置示例与运行避坑
下面给出一份完整的 Log4j2 全异步配置。由于已经通过 Log4jContextSelector 开启全异步，XML 里直接用普通 Console 和 RollingFile Appender，不需要再包装 AsyncAppender。配置中保留 monitorInterval 可以在运行时动态加载修改后的配置。
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" monitorInterval="30">
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
</Console>
<RollingFile name="RollingFile" fileName="logs/app.log"
filePattern="logs/app-%d{yyyy-MM-dd}-%i.log.gz">
<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
<Policies>
<TimeBasedTriggeringPolicy interval="1"/>
<SizeBasedTriggeringPolicy size="100 MB"/>
</Policies>
<DefaultRolloverStrategy max="20"/>
</RollingFile>
</Appenders>
<Loggers>
<Root level="info">
<AppenderRef ref="Console"/>
<AppenderRef ref="RollingFile"/>
</Root>
</Loggers>
</Configuration>
验证异步是否生效时，可以写一段简单的 Java 代码，用 100 次循环输出日志，观察业务线程是否快速返回，同时查看后台线程名是否包含 AsyncLogger 相关标识。示例如下：
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
public class AsyncLogDemo {
private static final Logger logger = LogManager.getLogger(AsyncLogDemo.class);
public static void main(String[] args) {
for (int i = 0; i < 100; i++) {
logger.info("异步日志测试: {}", i);
}
}
}
实际使用中经常遇到两个问题：一是在 log4j2.component.properties 中写好了选择器，但启动日志仍显示同步模式，这可能是因为文件没有被正确打包，或者 JVM 已经通过 -DLog4jContextSelector 覆盖了配置；二是日志格式里使用了 %class、%method 或 %line，这些定位信息会强制 Log4j2 获取调用栈，对异步性能影响很大，建议用 %logger 代替。只要避免这些坑，基于 Log4j2 的异步日志配置就能明显降低高并发下的记录开销。