Java异常携带TraceId的关键是上下文贯通与日志绑定，而非改造异常本身；需确保ThreadLocal/MDC中TraceId可用、线程池/异步调用正确传递、全局异常处理器中记录并标记错误。

在分布式链路追踪中，Java 异常需要携带 TraceId，核心是让异常发生时能自动关联当前请求的追踪上下文。这不依赖异常本身改造，而是靠统一的上下文传递 + 异常日志增强机制来实现。

确保 TraceId 在异常发生时仍可获取

TraceId 通常由链路追踪框架（如 SkyWalking、Pinpoint、OpenTelemetry 或 Sleuth/Zipkin）在请求入口（如 Servlet Filter、Spring WebMvc 拦截器）注入到 ThreadLocal 或当前 span 的上下文中。只要异常发生在同一线程、且未手动清理上下文，TraceId 就依然可用。

• 避免在线程池中丢失上下文：使用 TracedThreadPoolExecutor（Sleuth）或 WrappedExecutor（OpenTelemetry）包装线程池
• 异步调用（如 CompletableFuture）需显式传递上下文，否则子线程无法访问原始 TraceId
• 检查是否误调用了 Tracer.currentSpan().detach() 或清空了 MDC（如 Logback 的 MDC.clear()）

在日志中自动打印 TraceId（含异常堆栈）

大多数场景下，你不需要“往异常对象里塞 TraceId”，而是让日志框架（Logback/Log4j2）在打印异常时自动带上 TraceId。关键是把 TraceId 注入 MDC（Mapped Diagnostic Context）。

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

• Spring Boot + Sleuth：默认已将 traceId 和 spanId 写入 MDC，只需在 logback-spring.xml 中使用 %X{traceId}
• OpenTelemetry + Logback：通过 OpenTelemetryLogAppender 或自定义 Layout 提取当前 SpanContext
• 自研埋点：在全局异常处理器（@ControllerAdvice）中手动向 MDC 写入：MDC.put("traceId", Tracing.currentTracer().currentSpan().context().traceId());

全局异常处理器中主动记录带 TraceId 的错误事件

对于需要上报至 APM 后端（如 SkyWalking alarm、Jaeger error tag）的异常，应在统一异常处理处显式标记错误，并附加 TraceId 作为属性。

立即学习“Java免费学习笔记（深入）”；

• 使用 Span.setAttribute("error.type", e.getClass().getName())
• 调用 Span.recordException(e)（OpenTelemetry 推荐方式，自动提取 stack、message、type）
• 若用 SkyWalking，可通过 TraceContext.traceId() 获取并打点，或利用其 LogWriter 自动关联

避免常见陷阱

TraceId “没带上”往往不是技术不可行，而是上下文断裂或日志配置遗漏。

• 不要尝试继承 Exception 并加字段存 TraceId —— 违背异常设计初衷，且无法被 APM 工具识别
• 不要在 catch 块里只写 log.error("xxx", e) 却没配好 MDC 输出模板，导致日志里看不到 traceId
• RPC 调用抛出的远程异常（如 Dubbo 的 RemoteException）需在服务端记录，客户端看到的是封装后异常，TraceId 应由服务端保障

关键不在异常本身，而在上下文是否贯通、日志是否绑定、错误是否被 span 正确标记。