Java多线程中需用MDC传递TraceID：入口生成并put，日志pattern引用，结束时clear；跨线程须显式复制getCopyOfContextMap/setContextMap；APM如Sleuth/SkyWalking可自动透传。
在 Java 多线程环境中，要让日志中始终携带同一个追踪 ID（如 TraceID），关键不是“传递日志对象”，而是**传递上下文标识**，并确保日志框架能自动读取它。核心方案是使用 MDC（Mapped Diagnostic Context） 配合线程上下文隔离机制。
用 MDC 绑定和清理 TraceID
MDC 是 SLF4J 提供的线程局部存储工具，底层基于 ThreadLocal，天然支持单线程内上下文隔离。
- 在请求入口（如 WebFilter、Spring Interceptor 或 RPC 入口）生成唯一 TraceID，并放入 MDC：
MDC.put("traceId", UUID.randomUUID().toString()); - 在日志 pattern 中引用它，例如 Logback 的配置：
%d{HH:mm:ss.SSS} [%thread] [%X{traceId:-N/A}] %-5level %logger{36} - %msg%n - 务必在请求结束时清理，避免 ThreadLocal 泄漏（尤其在线程池场景）：
MDC.clear();
跨线程传递 TraceID（重点）
子线程默认不继承父线程的 MDC 内容。需显式复制：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- 使用
MDC.getCopyOfContextMap()获取当前上下文快照 - 在新线程启动前，用
MDC.setContextMap(...)注入 - 推荐封装成工具方法或使用支持透传的线程池（如
ThreadPoolTaskExecutor配合RequestContextHolder或自定义ThreadFactory） - 对
CompletableFuture，可借助copyMdcTo工具类，或使用supplyAsync(Supplier, Executor)+ 自定义 Executor 包装
与分布式链路追踪集成（如 SkyWalking / Sleuth）
如果已接入 APM 工具，通常无需手动管理 TraceID：
立即学习“Java免费学习笔记（深入）”；
- Spring Cloud Sleuth 会自动注入
traceId到 MDC，并在异步调用（@Async、WebClient、RabbitTemplate等）中透传上下文 - SkyWalking 的
agent也会拦截线程创建，自动复制上下文，只需确保使用其增强后的线程池或开启context_carrier插件 - 验证方式：在子线程日志中检查
%X{traceId}是否与主线程一致
注意事项
- 不要在
Runnable或Callable实现类的字段中缓存 MDC Map —— 它是线程局部的，且生命周期应与线程一致 - 避免在 finally 块中只调用
MDC.clear()而不 restore 原始 map（若需嵌套上下文） - Log4j2 用户注意：对应机制是
ThreadContext，用法类似但 API 不同（ThreadContext.put()/ThreadContext.clear()） - 协程（如 Quasar）或虚拟线程（Project Loom）场景需额外适配，因
ThreadLocal行为可能变化
