从原理到实践:MDC日志链路追踪指南

// 请求A和B的日志交错输出（按时间戳排序）
[2023-08-15 15:00:00.001] [thread-1] INFO  c.OrderController - 收到订单支付请求: ORD-123
[2023-08-15 15:00:00.001] [thread-2] INFO  c.OrderController - 收到订单支付请求: ORD-123
[2023-08-15 15:00:00.002] [thread-1] INFO  c.OrderService - 开始处理订单支付: ORD-123
[2023-08-15 15:00:00.003] [thread-2] INFO  c.OrderService - 开始处理订单支付: ORD-123
[2023-08-15 15:00:00.003] [thread-1] DEBUG c.OrderDao - 查询订单数据: ORD-123
[2023-08-15 15:00:00.004] [thread-2] WARN  c.OrderService - 等待订单锁: ORD-123
[2023-08-15 15:00:00.005] [thread-1] INFO  c.OrderService - 获取分布式锁成功: ORD-123
[2023-08-15 15:00:00.007] [thread-1] DEBUG c.OrderDao - 更新订单状态: ORD-123 [CREATED → PAID]
[2023-08-15 15:00:00.009] [thread-1] INFO  c.OrderService - 支付处理完成: ORD-123
[2023-08-15 15:00:00.010] [thread-1] INFO  c.OrderService - 释放订单锁: ORD-123
[2023-08-15 15:00:00.011] [thread-2] INFO  c.OrderService - 获取分布式锁成功: ORD-123
[2023-08-15 15:00:00.012] [thread-2] DEBUG c.OrderDao - 查询订单数据: ORD-123
[2023-08-15 15:00:00.013] [thread-2] INFO  c.OrderService - 订单已支付，跳过处理: ORD-123

public static void put(String key, String val) throws IllegalArgumentException {
    if (key == null) {
        throw new IllegalArgumentException("key parameter cannot be null");
    }
    if (mdcAdapter == null) {
        throw new IllegalStateException("MDCAdapter cannot be null. See also " + NULL_MDCA_URL);
    }
    mdcAdapter.put(key, val);
}

public void put(String key, String val) throws IllegalArgumentException {
    if (key == null) {
        throw new IllegalArgumentException("key cannot be null");
    }
    Map<String, String> oldMap = copyOnThreadLocal.get();
    Integer lastOp = getAndSetLastOperation(WRITE_OPERATION);

    if (wasLastOpReadOrNull(lastOp) || oldMap == null) {
        Map<String, String> newMap = duplicateAndInsertNewMap(oldMap);
        newMap.put(key, val);
    } else {
        oldMap.put(key, val);
    }
}

public void clear() {
    lastOperation.set(WRITE_OPERATION);
    copyOnThreadLocal.remove();
}

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-core</artifactId>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
</dependency>

<?xml version="1.0" encoding="UTF-8"?>
<configuration debug="false">
    <!--日志存储路径-->
    <property name="log" value="/mnt/applogs/" />
    <!-- 控制台输出 -->
    <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <!--输出格式化-->
            <pattern>[%X{TRACE_ID}]  %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
        </encoder>
    </appender>
    <!-- 按天生成日志文件 -->
    <appender name="file" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!--日志文件名-->
            <FileNamePattern>${log}/%d{yyyy-MM-dd}.log</FileNamePattern>
            <!--保留天数-->
            <MaxHistory>30</MaxHistory>
        </rollingPolicy>
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <pattern>[%X{TRACE_ID}]  %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
        </encoder>
        <!--日志文件最大的大小-->
        <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
            <MaxFileSize>10MB</MaxFileSize>
        </triggeringPolicy>
    </appender>
    <!-- 日志输出级别 -->
    <root level="INFO">
        <appender-ref ref="console" />
        <appender-ref ref="file" />
    </root>
</configuration>

public class TraceInterceptor implements HandlerInterceptor {
    private static final String TRACE_ID = "TRACE_ID";
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String traceId = UUID.randomUUID().toString().replace("-", "");
        //外部调用如果传入了TRACE_ID,直接传递即可
        if (StringUtils.isNotEmpty(request.getHeader("TRACE_ID"))){
            traceId=request.getHeader("TRACE_ID");
        }
        MDC.put(TRACE_ID, traceId);
        return true;
    }
    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler,
                                @Nullable Exception ex) {
        //请求处理完成,清理MDC信息                        
        MDC.remove(TRACE_ID);
    }
}

@Configuration
public class WebConfigurerAdapter implements WebMvcConfigurer {
    @Bean
    public TraceInterceptor traceInterceptor() {
        return new TraceInterceptor();
    }
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(traceInterceptor()).addPathPatterns("/**")
                .excludePathPatterns(WHITELIST);
    }
}

// DispatcherServlet.java
protected void doDispatch(HttpServletRequest request, HttpServletResponse response) throws Exception {
    // ... 获取 HandlerExecutionChain ...
    try {
        // 1. 执行 preHandle
        if (!mappedHandler.applyPreHandle(processedRequest, response)) {
          return;
        }
        // 2. 执行逻辑
        // 3. 执行 postHandle
        mappedHandler.applyPostHandle(processedRequest, response, mv);
        //4.组装结果
        processDispatchResult(processedRequest, response, mappedHandler, mv, dispatchException);
    } catch (Exception ex) {
      // 捕获异常，触发 afterCompletion（传入异常）
triggerAfterCompletion(processedRequest, response, mappedHandler, ex);
		} catch (Throwable err) {
triggerAfterCompletion(processedRequest, response, mappedHandler,
new NestedServletException("Handler processing failed", err));
		} finally {}
}

private void processDispatchResult(HttpServletRequest request, HttpServletResponse response,
    @Nullable HandlerExecutionChain mappedHandler, @Nullable ModelAndView mv,
    @Nullable Exception exception) throws Exception {
  boolean errorView = false;
  //...省略...
  if (mappedHandler != null) {
    // Exception (if any) is already handled..
    mappedHandler.triggerAfterCompletion(request, response, null);
  }
}

@Configuration
public class ScheduleConfig implements SchedulingConfigurer {
    @Override
    public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
        ThreadPoolTaskScheduler taskScheduler = new ThreadPoolTaskScheduler(){
          //...改造执行逻辑...
        };
        taskScheduler.setPoolSize(10); // 设置线程池大小
        taskScheduler.setThreadNamePrefix("scheduled-task-pool-"); // 设置线程名称前缀
        taskScheduler.initialize();
        taskRegistrar.setTaskScheduler(taskScheduler);
    }
}

// 包装任务的核心方法
private Runnable wrap(Runnable command) {
    return () -> {
        // 放置traceId
        String traceId=UUID.randomUUID().toString().replace("-", "");
        MDC.put("TRACE_ID", traceId);
        try {
            command.run();
        } finally {
            MDC.clear();
        }
    };
}
private <T> Callable<T> wrap(Callable<T> task) {
    return () -> {
        String traceId=UUID.randomUUID().toString().replace("-", "");
        MDC.put("TRACE_ID", traceId);
        try {
            return task.call();
        } finally {
            MDC.clear();
        }
    };
}

@XxlJob("demoJobHandler")
public void execute() {
    // 生成 traceId
    String traceId = UUID.randomUUID().toString().replace("-", "");
    MDC.put("TRACE_ID", traceId); // 存入任务执行线程的 MDC
    try {
        log.info("开始执行任务，traceId={}", traceId);
        // 业务逻辑...
    } finally {
        MDC.clear();
    }
}

@Component
@RocketMQMessageListener(consumerGroup = MQConstant.xxx,
        topic = "xxx", messageModel = MessageModel.CLUSTERING,
        consumeThreadMax = 5)
public class TestMQReceiver implements RocketMQListener<String> {
    @Override
    public void onMessage(String message) {
        String traceId = UUID.randomUUID().toString().replace("-", "");
        MDC.put("TRACE_ID", traceId); 
        try {
          //...执行消息消费逻辑...
        } catch (Throwable e) {
            log.error("代收订单结果跟踪MQ消费异常", e);
        }  finally {
            MDC.clear();
        }
    }
}