Java工程实践中日志框架的选择与配置

一、为什么要花时间做“选日志”这件事

1. 日志是线上故障的第一现场
   崩溃栈、慢 SQL、OOM、线程死锁……所有问题最终都会以日志的形式暴露出来。
2. 日志是性能的第二杀手
   一条不合理的 System.out.println() 在 5w TPS 的场景下可以把 CPU 打满；同步刷盘的 DEBUG 日志会把磁盘 I/O 拖垮。
3. 日志是团队协作的契约
   统一的日志格式、日志级别、链路追踪 ID，让 SRE、测试、开发、甚至算法同学都能用同一把“尺子”衡量系统健康度。

二、主流日志框架全景图

一句话总结：门面选 SLF4J，实现优先 Logback，追求极致性能再上 Log4j2 + AsyncLogger。

三、SLF4J + Logback：90% 场景的最优解

3.1 依赖坐标（Maven）

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.4.14</version>
</dependency>
<!-- 自动传递 slf4j-api -->

3.2 logback-spring.xml 配置示例

以下示例兼顾了：

• 按天滚动、大小切割
• 异步输出（AsyncAppender）
• Spring Profile 多环境隔离
• 链路追踪（TID）

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="30 seconds">

    <!-- 读取 Spring 变量 -->
    <springProperty scope="context"
                    name="LOG_HOME"
                    source="logging.file.path"
                    defaultValue="./logs"/>

    <!-- 通用属性 -->
    <property name="PATTERN"
              value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level [%X{TID}] %logger{36} - %msg%n"/>

    <!-- Console：开发环境彩色，生产环境关闭 -->
    <springProfile name="dev">
        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
                <pattern>%clr(%d{HH:mm:ss.SSS}){faint} %clr(%-5level) %clr([%X{TID}]){magenta} %clr(%logger{36}){cyan} - %msg%n</pattern>
            </encoder>
        </appender>
    </springProfile>

    <springProfile name="!dev">
        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>${PATTERN}</pattern>
            </encoder>
        </appender>
    </springProfile>

    <!-- 异步文件 -->
    <appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
        <queueSize>2048</queueSize>
        <discardingThreshold>0</discardingThreshold>
        <includeCallerData>false</includeCallerData>
        <appender-ref ref="ROLLING_FILE"/>
    </appender>

    <!-- 按天 & 100MB 滚动 -->
    <appender name="ROLLING_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_HOME}/app.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_HOME}/app.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>30</maxHistory>
            <totalSizeCap>10GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>${PATTERN}</pattern>
        </encoder>
    </appender>

    <!-- 根日志级别 -->
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="ASYNC_FILE"/>
    </root>

    <!-- 指定包级别 -->
    <logger name="com.example.demo.mapper" level="DEBUG" additivity="false">
        <appender-ref ref="ASYNC_FILE"/>
    </logger>

</configuration>

3.3 代码打印日志的正确姿势

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;

@RestController
public class OrderController {
    private static final Logger log = LoggerFactory.getLogger(OrderController.class);

    @GetMapping("/order/{id}")
    public OrderDTO query(@PathVariable Long id) {
        // 1. 设置链路追踪 ID
        MDC.put("TID", UUID.randomUUID().toString());

        // 2. 占位符，拒绝字符串拼接
        log.info("开始查询订单, orderId={}", id);

        OrderDTO dto = orderService.query(id);

        // 3. 条件日志，避免无效计算
        if (log.isDebugEnabled()) {
            log.debug("订单详情={}", JsonUtil.toJson(dto));
        }
        return dto;
    }
}

四、Log4j2：当性能成为瓶颈

4.1 性能差异基准（JMH 2023 报告节选）

差距主要来自 Disruptor 无锁队列 vs ArrayBlockingQueue。

4.2 依赖坐标

<!-- 必须排除 spring-boot-starter-logging -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>
<!-- log4j2 异步需要的 disruptor -->
<dependency>
    <groupId>com.lmax</groupId>
    <artifactId>disruptor</artifactId>
    <version>3.4.4</version>
</dependency>

4.3 log4j2.xml 关键点

<Configuration status="WARN">
    <Appenders>
        <!-- 随机读写文件，比 RandomAccessFile 还快 -->
        <RollingRandomAccessFile name="FILE"
                                 fileName="logs/app.log"
                                 filePattern="logs/app.%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout pattern="%d %p [%X{TID}] %c{1.} - %m%n"/>
            <Policies>
                <TimeBasedTriggeringPolicy/>
                <SizeBasedTriggeringPolicy size="100MB"/>
            </Policies>
        </RollingRandomAccessFile>
    </Appenders>

    <Loggers>
        <!-- 全局异步 Logger，必须加 disruptor -->
        <AsyncLogger name="com.example" level="info" includeLocation="false">
            <AppenderRef ref="FILE"/>
        </AsyncLogger>

        <Root level="info">
            <AppenderRef ref="FILE"/>
        </Root>
    </Loggers>
</Configuration>

4.4 GC-free 日志模板

Log4j2 6.0 起支持 Garbage-free 模式，通过复用 StringBuilder 避免 GC：

<PatternLayout pattern="%d{ABSOLUTE} %p [%t] %c{1.} - %m%n" 
               disableAnsi="false" 
               noConsoleNoAnsi="true" 
               charset="UTF-8"/>

五、结构化日志：ELK/ClickHouse 时代的刚需

5.1 Logstash Encoder（Logback）

<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>7.4</version>
</dependency>

<appender name="JSON" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/app.json</file>
    <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
        <providers>
            <timestamp/>
            <logLevel/>
            <loggerName/>
            <mdc/>
            <arguments/>
            <stackTrace/>
            <pattern>
                <pattern>{"service":"order-service","version":"1.0.0"}</pattern>
            </pattern>
        </providers>
    </encoder>
</appender>

输出示例：

{
  "@timestamp": "2025-07-13T14:33:12.123+08:00",
  "level": "INFO",
  "logger_name": "com.example.OrderController",
  "message": "开始查询订单",
  "orderId": 123456,
  "service": "order-service",
  "version": "1.0.0",
  "TID": "a1b2c3..."
}

5.2 Thread Context Map（Log4j2）

ThreadContext.put("orderId", "123456");
log.info("订单已支付");
ThreadContext.remove("orderId");

六、多环境 & 配置中心最佳实践

1. 本地开发：logback-spring.xml + spring.profiles.active=dev，控制台彩色。
2. 测试环境：配置中心推送 logback-test.xml，关闭控制台，日志级别 DEBUG。
3. 生产灰度：Apollo / Nacos 动态调整 <logger level="DEBUG"/>，无需重启。
4. Kubernetes：Sidecar 采集 /var/log/pods/**/**/*.log，统一格式为 JSON。

七、常见坑 & 排查清单

八、小结与决策树

┌─ 是否追求极致性能（>10w TPS）？
│   ├─ 是 → Log4j2 + AsyncLogger + disruptor
│   └─ 否 → 继续
├─ 是否已使用 Spring Boot？
│   ├─ 是 → Logback（默认）+ logback-spring.xml
│   └─ 否 → 依然推荐 Logback（依赖最少）
└─ 是否接入 ELK？
    ├─ 是 → JSON Encoder（Logstash or Log4j2 JSON Template）
    └─ 否 → PatternLayout