📚 课程目录第4章日志上下文与MDC

4、日志上下文与MDC：使用MDC实现请求链路追踪

在分布式系统中，一个用户请求往往跨越多个微服务、多个线程、多个异步边界。当系统出现异常时，如果没有统一的请求标识，开发人员需要在海量日志中手动拼凑调用链，效率极低。MDC（Mapped Diagnostic Context，映射诊断上下文）是SLF4J日志门面提供的一种线程绑定的上下文容器，能够在日志输出时自动注入TraceId、SpanId等链路标识，是实现结构化日志与分布式追踪的核心基础设施。

4.1 MDC的工作原理与线程绑定机制

MDC本质上是一个ThreadLocal实现的键值对容器，每个线程拥有独立的MDC副本。当请求进入系统时，在入口处（如Filter、Interceptor）生成或提取TraceId，并将其放入MDC；日志框架在输出日志时，通过配置的Pattern自动读取MDC中的值，拼接到日志行中。请求处理完毕后，必须在finally块中清除MDC，防止内存泄漏或线程复用导致的上下文污染。

  核心机制：MDC基于ThreadLocal实现，天然支持同步调用链；对于异步场景（线程池、消息队列），需要手动传递MDC上下文。

4.2 TraceId与SpanId的生成与传递规范

在分布式追踪体系中，TraceId标识一次完整的请求链路，SpanId标识链路中的单个服务调用单元。两者必须遵循全局唯一、可排序、低碰撞概率的生成策略。

标识符	生成方式	长度	传递范围
TraceId	UUID / Snowflake / 32位随机Hex	32字符（Hex）	全链路所有服务
SpanId	自增ID / 随机8位Hex	8~16字符	当前服务内部及下游
ParentSpanId	上游SpanId	与SpanId一致	仅用于构建父子关系

最佳实践：TraceId建议使用Snowflake算法生成，保证全局唯一且包含时间戳信息，便于日志检索时按时间范围过滤。SpanId使用自增序列即可，但需确保同一TraceId内不重复。

4.3 日志Pattern配置与MDC占位符

在logback.xml或log4j2.xml中，通过%X{key}占位符引用MDC中的值。以下是一个生产级Pattern配置示例：

<!-- logback.xml 配置示例 -->
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
        <pattern>
            %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level
            [%X{traceId}] [%X{spanId}] %logger{36} - %msg%n
        </pattern>
    </encoder>
</appender>

<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>/var/log/app/app.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
        <fileNamePattern>/var/log/app/app.%d{yyyy-MM-dd}.log</fileNamePattern>
        <maxHistory>30</maxHistory>
    </rollingPolicy>
    <encoder>
        <pattern>
            %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level
            [%X{traceId}] [%X{spanId}] %logger{36} - %msg%n
        </pattern>
    </encoder>
</appender>

配置完成后，日志输出效果如下：

2025-03-21 14:30:22.456 [http-nio-8080-exec-3] INFO
[a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6] [span-001]
com.example.OrderService - 创建订单成功，orderId=10086

4.4 异步场景下的MDC传递

当使用线程池、CompletableFuture、消息队列等异步机制时，MDC不会自动跨线程传递。必须显式将MDC上下文从父线程拷贝到子线程。以下是三种常见场景的解决方案：

异步场景	传递方式	代码示例
线程池（ThreadPoolExecutor）	自定义Runnable包装器	`Runnable wrapper = () -> { MDC.setContextMap(context); try { runnable.run(); } finally { MDC.clear(); } };`
CompletableFuture	使用`thenApplyAsync`时传入自定义线程池	`CompletableFuture.supplyAsync(() -> { MDC.setContextMap(ctx); ... }, mdcAwareExecutor)`
消息队列（Kafka/RabbitMQ）	在消息头中传递TraceId，消费端重建MDC	`headers.put("traceId", MDC.get("traceId"))`

避坑指南：不要直接使用MDC.getCopyOfContextMap()在子线程中设置MDC后忘记清理。子线程执行完毕后必须调用MDC.clear()，否则线程池复用会导致上下文错乱。推荐使用Spring的ThreadPoolTaskExecutor配合TaskDecorator自动处理MDC传递。

4.5 基于Filter的MDC自动注入实现

在Spring Boot应用中，通过实现javax.servlet.Filter或HandlerInterceptor，可以在请求入口处自动完成TraceId的生成、注入和清理。以下是一个完整的Filter实现：

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class TraceIdFilter implements Filter {

    private static final String TRACE_ID_HEADER = "X-Trace-Id";
    private static final String SPAN_ID_HEADER = "X-Span-Id";

    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        HttpServletResponse httpResponse = (HttpServletResponse) response;

        try {
            // 1. 从请求头获取TraceId，若不存在则生成新TraceId
            String traceId = httpRequest.getHeader(TRACE_ID_HEADER);
            if (traceId == null || traceId.isEmpty()) {
                traceId = generateTraceId(); // Snowflake或UUID
            }

            // 2. 生成当前SpanId
            String spanId = generateSpanId();

            // 3. 注入MDC
            MDC.put("traceId", traceId);
            MDC.put("spanId", spanId);

            // 4. 将TraceId写回响应头，方便客户端追踪
            httpResponse.setHeader(TRACE_ID_HEADER, traceId);

            // 5. 执行后续业务逻辑
            chain.doFilter(request, response);
        } finally {
            // 6. 必须清理MDC，防止内存泄漏
            MDC.clear();
        }
    }

    private String generateTraceId() {
        // 使用Snowflake算法或UUID
        return UUID.randomUUID().toString().replace("-", "");
    }

    private String generateSpanId() {
        // 简单自增或随机8位Hex
        return Long.toHexString(ThreadLocalRandom.current().nextLong());
    }
}

4.6 MDC与分布式追踪系统的集成

MDC不仅用于日志输出，更是连接日志系统与分布式追踪系统（如Jaeger、Zipkin、SkyWalking）的桥梁。通过将TraceId和SpanId注入MDC，可以实现以下能力：

日志与追踪联动：在日志中点击TraceId可直接跳转到追踪系统的链路详情页。
跨服务调用链还原：下游服务通过HTTP头或RPC元数据接收上游的TraceId，保证全链路标识一致。
异常快速定位：根据TraceId聚合所有相关日志，无需人工逐行搜索。

4.7 生产环境MDC使用规范

  关键指标：引入MDC后，单条日志体积增加约60~80字节（TraceId 32字符 + SpanId 8字符 + 分隔符），对磁盘IO和网络传输影响可忽略不计。但日志检索效率提升10倍以上，故障定位时间从小时级缩短到分钟级。

在生产环境中，建议遵循以下规范：

必填字段：traceId、spanId、parentSpanId（可选）、userId（可选）、env（环境标识）。
字段长度控制：TraceId固定32字符Hex，SpanId固定8字符Hex，避免过长影响日志解析性能。
清理时机：在Filter的finally块、异步任务的finally块、RPC调用的回调中必须清理MDC。
监控告警：对MDC中TraceId为空的情况进行监控，一旦发现立即告警，说明链路追踪出现断裂。
兼容性：确保日志采集工具（Filebeat、Fluentd）的解析规则与MDC字段名一致，避免字段丢失。