📚 课程目录第4章日志变更门禁定义

4. Trace ID 与日志关联：日志框架集成与跨服务传递

在分布式系统中，一次用户请求往往跨越多个微服务实例。若日志之间缺乏关联标识，排查问题时只能依靠时间戳和人工猜测，效率极低。本章聚焦于如何通过 MDC（Mapped Diagnostic Context） 机制，将 Trace ID 自动注入日志上下文，并实现跨服务透明传递，从而构建可追溯的日志链路。

4.1 核心概念：MDC 与 Trace ID 注入原理

MDC 是 SLF4J 提供的一种线程绑定的诊断上下文容器。每个线程拥有独立的 MDC 副本，日志框架在输出日志时，可以从 MDC 中提取预设的键值对（如 traceId、spanId）并格式化到日志行中。

概念	说明	生命周期
MDC	线程局部 Map，存储诊断上下文	随线程创建而存在，需手动清除
Trace ID	全局唯一请求标识，贯穿全链路	从入口生成，跨服务传递
Span ID	单个服务内的调用单元标识	每次 RPC 调用生成新 ID
日志 Pattern	日志格式模板，引用 MDC 变量	配置时定义，运行时解析

最佳实践：MDC 中的键名建议统一使用 traceId 和 spanId，避免团队内部因命名不一致导致日志解析失败。

4.2 Logback 集成：配置与代码实现

Logback 是 Spring Boot 默认的日志框架。集成 MDC 只需两步：配置 Pattern 和 在入口处注入 Trace ID。

4.2.1 logback-spring.xml 配置

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- 引用 MDC 中的 traceId 和 spanId -->
    <property name="LOG_PATTERN"
              value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} [%X{traceId:-NONE}] [%X{spanId:-NONE}] - %msg%n" />

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

    <root level="INFO">
        <appender-ref ref="CONSOLE" />
    </root>
</configuration>

关键点：%X{traceId:-NONE} 表示从 MDC 中读取 traceId，若不存在则输出 NONE。

4.2.2 过滤器自动注入 Trace ID

@Component
public class TraceIdFilter implements Filter {

    private static final String TRACE_ID = "traceId";

    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) throws IOException, ServletException {
        try {
            // 从请求头获取 Trace ID，若不存在则生成新 ID
            String traceId = ((HttpServletRequest) request).getHeader(TRACE_ID);
            if (traceId == null || traceId.isEmpty()) {
                traceId = UUID.randomUUID().toString().replace("-", "");
            }
            MDC.put(TRACE_ID, traceId);
            chain.doFilter(request, response);
        } finally {
            // 请求结束后必须清除，防止线程复用导致上下文污染
            MDC.clear();
        }
    }
}

注意：异步任务或线程池中，MDC 不会自动传递。需要手动将父线程的 MDC 上下文拷贝到子线程，或使用 Hystrix、ThreadPoolTaskExecutor 的装饰器模式。

4.3 Log4j2 集成：配置与代码实现

Log4j2 的 MDC 机制与 Logback 类似，但配置语法略有不同。以下为 Log4j2 的典型配置：

4.3.1 log4j2-spring.xml 配置

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %c{1} [%X{traceId:-NONE}] [%X{spanId:-NONE}] - %msg%n" />
        </Console>
    </Appenders>

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

4.3.2 使用 ThreadContext 替代 MDC

Log4j2 推荐使用 ThreadContext 类操作诊断上下文，用法与 MDC 完全一致：

import org.apache.logging.log4j.ThreadContext;

public class Log4j2TraceIdFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) throws IOException, ServletException {
        try {
            String traceId = ((HttpServletRequest) request).getHeader("traceId");
            if (traceId == null) {
                traceId = UUID.randomUUID().toString();
            }
            ThreadContext.put("traceId", traceId);
            chain.doFilter(request, response);
        } finally {
            ThreadContext.clearAll();
        }
    }
}

4.4 跨服务传递 Trace ID

在微服务架构中，Trace ID 必须通过 RPC 协议（HTTP/gRPC/消息队列）在服务间传递。以 HTTP 为例，通常将 Trace ID 放入请求头中。

4.4.1 使用 RestTemplate 传递

@Bean
public RestTemplate restTemplate() {
    return new RestTemplate();
}

// 在调用下游服务时，从当前 MDC 获取 Trace ID 并设置到请求头
public String callDownstream(String url) {
    String traceId = MDC.get("traceId");
    HttpHeaders headers = new HttpHeaders();
    headers.set("traceId", traceId);
    HttpEntity<String> entity = new HttpEntity<>(headers);
    return restTemplate.exchange(url, HttpMethod.GET, entity, String.class).getBody();
}

4.4.2 使用 OpenFeign 拦截器自动传递

@Component
public class TraceIdFeignInterceptor implements RequestInterceptor {
    @Override
    public void apply(RequestTemplate template) {
        String traceId = MDC.get("traceId");
        if (traceId != null) {
            template.header("traceId", traceId);
        }
    }
}

4.4.3 消息队列场景

对于 RabbitMQ / Kafka 等异步消息，需要在生产者发送消息时将 Trace ID 写入消息头，消费者消费时再注入 MDC：

// 生产者
Message message = MessageBuilder
    .withPayload(payload)
    .setHeader("traceId", MDC.get("traceId"))
    .build();

// 消费者
@RabbitListener(queues = "order.queue")
public void handleMessage(Message message) {
    String traceId = (String) message.getMessageProperties().getHeaders().get("traceId");
    MDC.put("traceId", traceId);
    try {
        // 业务处理
    } finally {
        MDC.clear();
    }
}

4.5 整体架构与数据流

下图展示了 Trace ID 从入口网关到下游服务的完整传递路径，以及 MDC 在各节点中的注入与输出过程。

4.6 日志框架对比与选型建议

特性	Logback	Log4j2
MDC 实现类	`org.slf4j.MDC`	`org.apache.logging.log4j.ThreadContext`
异步日志性能	良好（基于 LMAX Disruptor）	优秀（无锁异步 Appender）
配置热加载	支持（自动扫描）	支持（更灵活）
与 Spring Boot 兼容性	默认集成，开箱即用	需排除 Logback 依赖
推荐场景	中小型项目、快速启动	高并发、低延迟、复杂路由

  选型建议：若团队已使用 Spring Boot 且无特殊性能要求，优先选择 Logback 以降低集成成本。若系统对日志吞吐量有极高要求（如每秒数万条日志），建议切换至 Log4j2 的异步 Appender。

4.7 常见问题与避坑指南

MDC 内存泄漏：线程池中的线程被复用，若未在 finally 块中调用 MDC.clear()，旧 Trace ID 会污染后续请求。务必使用 try-finally 保证清除。
异步线程丢失 Trace ID：使用 @Async 或 CompletableFuture 时，子线程无法继承父线程的 MDC。解决方案：使用 ThreadPoolTaskExecutor 的 TaskDecorator 手动拷贝。
请求头传递遗漏：某些 HTTP 客户端（如 WebClient）默认不传递自定义头。需显式配置拦截器或 ExchangeFilterFunction。
日志 Pattern 未生效：检查配置文件中是否使用了正确的占位符 %X{traceId}，并确认 MDC 键名与 Pattern 中的键名完全一致。