MDC（Mapped Diagnostic Context）是日志框架中非常实用的诊断上下文工具，最典型的用法就是存放traceId、userId等链路信息，让每条日志都自动携带上下文，方便排查线上问题。然而一旦把日志改成异步输出，或者业务代码里用了线程池，很多开发者就会发现MDC里的值莫名其妙丢了，日志里traceId全是空的。要彻底解决这个问题，先得弄清楚MDC到底是怎么存储数据的。
MDC的底层原理：为什么数据会丢
以Logback为例，MDC.put("traceId", "xxx")这行代码最终会把值放进一个ThreadLocal变量中。查看Logback源码可以看到，LogbackMDCAdapter内部维护了一个InheritableThreadLocal，业务线程调用put时，数据只存在于当前线程的副本里。打印日志时，PatternLayout中的%X{traceId}转换符会去当前线程读取这个值并渲染到日志内容中。
理解了这一点，丢失的原因就非常清晰了。异步日志的工作方式是：业务线程构造日志事件后，把事件丢进一个队列，由一条独立的日志线程负责真正的格式化和落盘。日志事件本身并不携带MDC的快照，而Logback的AsyncAppender默认在入队前其实会复制MDC，但如果你用的是自定义线程池执行业务逻辑，情况就完全不同了。
业务侧的丢失场景更常见：在Tomcat的工作线程里调用了MDC.put，然后把任务提交到自己的线程池，任务内部打印日志时运行在池中线程上，这个线程的ThreadLocal里根本没有traceId。同理，使用CompletableFuture.supplyAsync、parallel stream、@Async注解等一切涉及线程切换的手段，都会让MDC上下文断裂。这不是框架的bug，而是ThreadLocal机制天然的作用域限制。
方案一：手动传递MDC上下文
最直接的办法是在任务提交前取出MDC快照，在任务内部先恢复再清理。这种方案不依赖任何第三方库，理解成本最低，适合线程池使用点不多的小项目。核心思路是用MDC.getCopyOfContextMap()获取当前上下文的副本，传递给任务，任务执行时通过MDC.setContextMap还原。
public class MdcTaskWrapper implements Runnable {
private final Runnable task;
private final Map<String, String> contextMap;
public MdcTaskWrapper(Runnable task) {
this.task = task;
// 在提交线程捕获MDC快照
this.contextMap = MDC.getCopyOfContextMap();
}
@Override
public void run() {
Map<String, String> old = MDC.getCopyOfContextMap();
try {
if (contextMap != null) {
MDC.setContextMap(contextMap);
}
task.run();
} finally {
// 恢复线程原有上下文，避免线程复用导致脏数据
if (old != null) {
MDC.setContextMap(old);
} else {
MDC.clear();
}
}
}
}
// 使用方式
executor.submit(new MdcTaskWrapper(() -> {
log.info("这条日志能正确打印traceId");
}));这个方案有几个需要注意的细节。第一，finally块里的恢复操作必不可少，因为线程池中的线程会被复用，如果不清理，上一个请求的traceId可能污染下一个请求的日志，这种隐形的串号问题比丢数据更难排查。第二，如果项目里有大量直接使用ExecutorService的地方，可以考虑封装一个工厂方法统一包装任务，避免遗漏。
手动传递的缺点也很明显：侵入性强，每个提交点都要改代码，而且Callable、Runnable、CompletableFuture等不同形态的任务需要分别处理，代码重复度高。一旦某处忘了包装，日志照样丢失，属于防御性不够强的方案。
方案二：使用TransmittableThreadLocal统一解决
阿里的开源框架transmittable-thread-local（TTL）专门解决线程池场景下的上下文传递问题，它是目前生产环境中最主流的方案。TTL的核心思想是在任务提交时对ThreadLocal值做一次capture，任务执行时做replay，执行完做restore，整个过程通过装饰线程池来自动完成，业务代码零侵入。
要让MDC配合TTL工作，通常的做法是把日志框架的MDC适配器替换为基于TransmittableThreadLocal的实现，同时用TtlExecutors.getTtlExecutorService()包装线程池。这样任何提交到该线程池的任务，MDC上下文都会自动跟着过去。
// 1. 自定义基于TTL的MDC适配器
public class TtlMDCAdapter extends LogbackMDCAdapter {
// 将内部存储替换为TransmittableThreadLocal
// 详见ttl-transmittable-thread-local官方示例
}
// 2. 替换适配器（通过反射修改LogbackMDCAdapter，或参考官方mdc模块）
// 3. 包装线程池
ExecutorService ttlExecutor = TtlExecutors.getTtlExecutorService(executorService);
// 4. 业务代码无需任何改动
executor.submit(() -> log.info("traceId自动传递"));官方的ttl项目里其实提供了现成的ttl-mdc集成方案，Logback和Log4j2都有对应的适配器实现，直接引入依赖按照README配置即可。相比手动传递，TTL的优势在于集中治理：只需要在基础设施层包装一次线程池，所有业务方都受益，还支持ForkJoin、Timer、ScheduledExecutorService等各种并发组件。
需要注意TTL的版本兼容问题。JDK 21引入虚拟线程后，TTL的某些旧版本存在适配缺陷，升级前务必确认版本支持情况。另外TTL要求ttl-agent或者显式包装二选一，如果用字节码增强方式，需要在启动参数中挂载agent，容器化部署时要记得把agent包打进镜像。
方案三：从日志框架层面解决
如果丢失只发生在日志异步化这一环，Logback本身就提供了答案。AsyncAppender在设计时已经考虑到了MDC问题：它在事件入队时会调用prepareForDeferredProcessing()，其中包含对MDC快照的处理，日志线程格式化时使用的是事件里携带的快照而非自己线程的MDC。因此单纯使用官方AsyncAppender，日志中的MDC一般是不会丢的。
<appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
<!-- 开启包含CallerData会显著影响性能，MDC默认已随事件传递 -->
<queueSize>1024</queueSize>
<discardingThreshold>0</discardingThreshold>
<neverBlock>true</neverBlock>
<appender-ref ref="FILE"/>
</appender>但对于Log4j2用户，情况有所不同。Log4j2的异步日志基于Disruptor实现，默认配置下MDC不一定随事件传递，需要确认使用的是异步日志上下文以及相关参数配置。如果发现异步模式下MDC丢失，可以检查AsyncLogger的配置，必要时在log4j2.component.properties中开启相应选项。
还有一种思路是彻底绕开ThreadLocal，把traceId等上下文信息作为日志事件的显式字段传递。例如通过SLF4J的占位符手动拼接，或者使用结构化日志把上下文放进JSON字段，配合APM系统按traceId聚合。这种方案改造成本高，但语义最清晰，微服务架构下配合链路追踪组件（如SkyWalking、OpenTelemetry）使用时，traceId本身就由追踪框架注入和传播，MDC只是它的一个展示通道，这时应该优先保证追踪框架的上下文传播配置正确。
方案对比与选型建议
三种方案各有定位。手动传递适合快速止血和线程池使用点少的场景，优点是无依赖、可控，缺点是侵入性强、容易遗漏。TTL适合中大型项目统一治理，一次封装全局生效，是长期维护成本最低的选择，但引入了第三方依赖，且要处理与虚拟线程等新特性的兼容。日志框架层面的配置解决的是异步落盘环节的丢失，如果丢数据的根源在业务线程池，它帮不上忙。
实际排查时建议先定位丢失发生在哪一环：如果同步日志里MDC正常、异步日志丢失，优先查AsyncAppender或Log4j2配置；如果线程池里的业务日志丢失，那就是上下文传递问题，上TTL或手动包装。上线前可以用一个打印全链路日志的压测用例验证，确认每条日志的traceId都完整，再不用担心线上排障时两眼一抹黑。
MDC异步日志ThreadLocal修改时间：2026-09-02 01:58:39