在 Java 项目中实现分布式追踪系统时，traceId 的传递机制可以通过以下图示来说明：
-
分布式追踪系统架构图
[用户请求]
│
▼
[API网关] → 生成全局 traceId
│
▼
[服务A] → 接收 traceId → 日志记录 → 调用服务B
│ ▲
│ │ 传递 traceId
▼ │
[服务B] → 接收 traceId → 日志记录 → 调用数据库
│ ▲
│ │ 传递 traceId
▼ │
[数据库] → 记录 traceId 到 SQL 日志
│
▼
[消息队列] → 传递 traceId
│
▼
[服务C] → 处理消息并记录 traceId -
traceId 传递机制图解
2.1 HTTP 请求中的传递
[客户端] → GET /api/data
Header: X-Trace-Id: abc123
│
▼
[服务A] → 从 Header 获取 traceId
│
▼
[服务A] → 调用服务B: POST /internal/data
Header: X-Trace-Id: abc123 (保持相同)2.2 RPC 调用中的传递
[服务A] → Dubbo RPC 调用服务B
┌───────────────────────────┐
│ Invocation │
│ - method: getData │
│ - attachments: │
│ traceId = "abc123" │
└───────────────────────────┘
│
▼
[服务B] → 从 attachments 获取 traceId2.3 消息队列中的传递
服务A\] → 发送消息到 RabbitMQ/Kafka
┌───────────────────────────┐
│ Message Properties │
│ headers: │
│ traceId = "abc123" │
└───────────────────────────┘
│
▼
\[服务C\] → 从消息属性获取 traceId
3. 线程上下文管理
3.1 同步请求中的上下文
┌──────────────────────┐
│ ThreadLocal │
│ traceId = "abc123" │
│ MDC (日志上下文) │
└──────────────────────┘
3.2 异步线程中的上下文传递
主线程 → 提交任务到线程池
┌──────────────────────┐ ┌──────────────────────┐
│ TransmittableThread │ → │ 线程池线程 │
│ traceId = "abc123" │ │ traceId = "abc123" │
└──────────────────────┘ └──────────────────────┘
任务执行前复制 任务执行时使用
4. 日志系统中的 traceId 集成
2023-08-15 10:30:25 \[http-nio-8080-exec-1\] \[traceId:abc123\] INFO c.e.s.ServiceA - 处理请求
2023-08-15 10:30:26 \[http-nio-8080-exec-1\] \[traceId:abc123\] DEBUG c.e.s.ServiceA - 调用服务B
2023-08-15 10:30:27 \[http-nio-8080-exec-3\] \[traceId:abc123\] INFO c.e.s.ServiceB - 接收请求
2023-08-15 10:30:28 \[task-pool-1\] \[traceId:abc123\] INFO c.e.s.AsyncService - 异步任务开始
5. 全链路追踪示意图
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐
│ 网关 │ │ 服务A │ │ 服务B │ │ 数据库 │
│ traceId生成 │ ⇒⇒⇒ │ 记录日志 │ ⇒⇒⇒ │ 记录日志 │ ⇒⇒⇒ │ SQL日志 │
│ abc123 │ │ \[abc123\] │ │ \[abc123\] │ │ \[abc123\] │
└────────────┘ └────────────┘ └──────┬──────┘ └──────────┘
⇓ ⇓
┌────────────┐ │ ┌────────────┐
│ 消息队列 │⇐═⇘ │ 服务C │
│ \[abc123\] │ │ \[abc123\] │
└────────────┘ └────────────┘
关键组件说明：
1. traceId 生成器：
◦ 在系统入口（网关或第一个服务）生成唯一 ID
◦ 格式：\[应用标识\]-\[时间戳\]-\[随机数\]（例：APP1-1692081025-7d3f）
2. 上下文传播器：
◦ HTTP：通过 Header（X-Trace-Id）
◦ RPC：通过调用附件（Attachment）
◦ MQ：通过消息属性（Properties）
◦ 线程：通过 ThreadLocal + MDC
3. 日志集成：
◦ 日志框架配置中添加 %X{traceId}
◦ 所有日志自动包含当前 traceId
4. 异步支持：
◦ 使用 TransmittableThreadLocal 解决线程池上下文传递
◦ 配合 TaskDecorator 包装 Runnable
5. 监控集成：
◦ 将 traceId 传递给监控系统（如 Zipkin）
◦ 实现全链路追踪可视化
这种设计确保了在分布式系统中，从一个请求进入系统开始，到经过多个服务、数据库操作、异步任务处理，再到最终响应，整个过程中的所有日志和操作都能通过同一个 traceId 关联起来，极大地方便了问题排查和系统监控。
在 Java 项目中实现统一的 traceId（请求追踪 ID）是分布式系统追踪的关键，以下是几种常用且可靠的实现方案：
*** ** * ** ***
#### 方案一：Servlet Filter + MDC（推荐）
// TraceId 工具类
public class TraceIdUtil {
public static final String TRACE_ID = "traceId";
public static String generateTraceId() {
// 使用 UUID + 时间戳确保唯一性
return "TRC-" + System.currentTimeMillis() + "-" + UUID.randomUUID().toString().substring(0, 8);
}
}
或者：
import java.util.UUID;
public class TraceIdGenerator {
// 生成标准UUID格式的TraceId
public static String generateUUIDTraceId() {
return UUID.randomUUID().toString().replace("-", "");
}
// 生成更短的UUID变种(32位)
public static String generateShortUUIDTraceId() {
return UUID.randomUUID().toString().replace("-", "");
}
// 生成带前缀的TraceId
public static String generatePrefixedTraceId(String prefix) {
return prefix + "-" + generateShortUUIDTraceId();
}
}
// 过滤器实现
@WebFilter("/*")
public class TraceIdFilter implements Filter {
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
throws IOException, ServletException {
try {
// 1. 生成/传递 traceId
HttpServletRequest httpRequest = (HttpServletRequest) request;
String traceId = Optional.ofNullable(httpRequest.getHeader("X-Trace-Id"))
.orElseGet(TraceIdUtil::generateTraceId);
// 2. 存入 MDC（日志上下文）
MDC.put(TraceIdUtil.TRACE_ID, traceId);
// 3. 设置到请求属性（供业务代码使用）
httpRequest.setAttribute(TRACE_ID_ATTRIBUTE, traceId);
// 4. 传递给下游（设置响应头）
HttpServletResponse httpResponse = (HttpServletResponse) response;
httpResponse.setHeader("X-Trace-Id", traceId);
chain.doFilter(request, response);
} finally {
// 5. 请求结束后清除 MDC
MDC.clear();
}
}
}
**日志配置（logback.xml）**：