先说结论

链路追踪解决的问题是:一次跨 5 个服务的请求失败了,日志散落在 5 台机器上,怎么把它们串起来? 答案是一个全程透传的 traceId。整套体系只有三个概念:trace(一次完整调用)、span(一次方法或一次 RPC)、span 之间的父子关系。落地时盯住三件事:上下文透传、日志带 traceId、异步线程不丢上下文。这三件事里任何一件断了,链路图就出现断点,traceId 退化成一串"只在单机有意义的普通日志前缀"——这是链路追踪项目最常见的失败形态:系统都接了,链路串不起来。

核心模型

traceId: abc123(全程不变)
  spanA 网关        (spanId=1)
    └── spanB 订单服务 (spanId=1.2, parent=1)
          └── spanC 库存服务 (spanId=1.2.3, parent=1.2)
  • traceId 在入口生成,HTTP 调用放在请求头里透传(主流标准是 W3C 的 traceparent 头,老一代是 B3 的 X-B3-TraceId);
  • spanId + parentSpanId 表达调用树,配合时间戳还原耗时瀑布图,一眼看出慢在哪一跳;
  • span 的四要素是:名称、开始时间、耗时、携带的 tags(比如下游返回码、SQL 语句摘要),排查时瀑布图上点开 span 看的就是这些。

跨协议透传的规则也要记一条:HTTP 走请求头,MQ 场景把上下文塞进消息属性,RPC 框架走 attachment——原理相同,载体不同。消息队列是断链重灾区之一,生产者发的消息丢了上下文,消费者侧就会开出一棵"没有父亲的新树"。

span 还有两个常被忽略的成员:tags(键值对,记录返回码、SQL 摘要、租户 ID 等检索维度)与 events(span 生命内的关键时间点,比如重试发生在第几毫秒)。排查"哪一跳出问题"看瀑布图,定位"那一跳内部发生了什么"看 tags 与 events——录入哪些 tags 是埋点规范的一部分,规范缺失时链路平台会退化成只能看耗时的瀑布图。

Java 技术栈的现状

Spring Cloud Sleuth 已进入维护模式,官方方向是 Micrometer Tracing(Spring Boot 3.x 配套),底层桥接 OpenTelemetry 或 Brave;存储与展示通常配 Zipkin 或 Jaeger。存量 Spring Boot 2.x 项目继续用 Sleuth + Zipkin 没问题,新项目直接上 Micrometer Tracing。两者使用姿势几乎一致:引依赖、配导出地址、日志 pattern 里加 traceId,迁移成本可控,主要工作是回归验证异步任务的上下文传播。

存储选型跟随规模:Zipkin 自带的存储与 Elasticsearch 后端覆盖大多数团队的量级,Jaeger 及更大的可观测后端在需要服务依赖图、更长保留期时更合适。选型的关键是先定"保留多少天、错误链路能否被快速检索",再倒推存储方案——链路数据的价值集中在故障排查的短窗口期,盲目拉长保留期是最常见的成本浪费。

最小接入配置(Spring Boot 3.x + Micrometer Tracing + Zipkin 导出):

management:
  tracing:
    sampling:
      probability: 0.1        # 采样率,全量 1.0,生产按容量定
  zipkin:
    tracing:
      endpoint: http://zipkin:9411/api/v2/spans
logging:
  pattern:
    level: "%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]"

最后一行的意义:每条日志自动带上 traceId/spanId。拿到用户反馈里的一个 traceId,就能在日志平台捞全所有服务的相关日志——这是链路追踪最直接的收益,也是向业务方解释"这套东西有什么用"时最好讲的一句话。

三个实战要点

1. traceId 要"传进来也要传出去"

入口没收到 traceId 就自己生成,并写回响应头(如 X-Trace-Id)。前端报障时让用户直接提供这个值,排障效率远高于"让用户回忆几点几分点了什么按钮"。配合网关把响应头的 traceId 统一打出,客服工单模板里也加上这个字段,排障入口就标准化了。

生成规则上有一个取舍要写进接入文档:请求头里已有 traceId 就沿用,没有才生成——上游已接链路追踪、下游又无条件自造 ID,一次调用在两边就是两个案件号,链路对不上还查不出原因。跨团队的接入规约里明确这个优先级,能省掉大量"链路对不上"的扯皮。

2. 异步与线程池是断链重灾区

trace 上下文存在 ThreadLocal 里,线程池换线程就断。两个必做项:

  • 自定义线程池统一加任务装饰器,Micrometer Tracing 的 ContextSnapshot 配 context-propagation 库负责跨线程传播;
  • @Async 生效的前提是走 Spring 管理的线程池,自己 new Thread 没有装饰逻辑,必然丢上下文。
// 错误写法:裸线程池直接跑任务,trace 上下文在换线程那一刻丢失
ExecutorService pool = Executors.newFixedThreadPool(4);
pool.submit(() -> orderService.notify(orderId));
// 子任务日志里 traceId 是空的,链路瀑布图在这里断成两截,
// 排障时上游链路查得到、下游执行查不到,等于白埋一半点
// 正确写法:线程池统一配置上下文装饰器(Spring Framework 6.1+ 提供)
@Bean
public ThreadPoolTaskExecutor bizExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setCorePoolSize(8);
    executor.setThreadNamePrefix("biz-");
    // 装饰器在提交任务时捕获 trace / MDC 上下文,在执行线程里恢复,
    // 子任务日志的 traceId 与主链路一致,链路图不再断链
    executor.setTaskDecorator(new ContextPropagatingTaskDecorator());
    return executor;
}

治理这类问题的抓手是规约:全项目禁止裸 new Thread 与裸 Executors.newXxxPool,线程池一律走统一 Bean 并强制带装饰器——断链问题靠逐个修是修不完的,只能靠入口收敛。

3. 采样率是成本与排查价值的平衡

全量采样在高 QPS 下会让存储成本失控;采样太低又抓不到偶现问题。常见策略是错误请求 100% 采样 + 正常请求低比例采样,Micrometer Tracing 支持自定义采样器实现这个规则。采样率的调整要跟着容量走:大促前临时调低正常流量采样、保留错误全量,活动结束后恢复——把采样率当成一个可运营的配置项而不是写死的数字,是采样策略落地的最后一步。

采样策略规则适用场景代价
全量采样(probability=1.0)每个请求都记录测试环境、低流量核心服务高 QPS 下存储成本失控
固定概率采样按比例丢弃正常链路一般生产服务偶现问题可能采不到
错误全量 + 正常低比例自定义 Sampler 按状态决策生产主流选择需要自定义采样器实现
尾部采样链路结束后按耗时/错误决定保留慢调用专项分析收集端要缓冲整条链路,架构复杂

一句话收尾:traceId 是分布式系统的"案件编号":入口生成、处处透传、日志落盘,剩下的交给 span 树还原真相。

生产案例

一次支付回调偶现失败的工单转过来时,用户只提供了订单号和大概时间,按老办法要跨四个服务的日志平台各查一轮,靠时间戳对齐猜测哪几条是同一笔请求。这次直接从网关响应头拿到这笔请求的 traceId,在链路平台拉出完整的 span 瀑布图:回调进入支付服务后转发风控,慢点立刻显形在风控服务调下游黑名单服务的那个 span 上,展开 tags 看到连接池等待的痕迹,连查几次历史链路都是同一形态——下游连接池偶发耗尽,一次会话完成定位。让对方扩连接池上限后,同类偶现失败再没有出现。这个案例后来被反复引用,不是为了说明工具多强,而是说明一个事实:没有 traceId 时,跨服务问题排查的瓶颈不是技术,是"这几条日志是不是同一笔请求"永远无法确认。

检查清单

  • 入口生成或接收 traceId,并写回响应头 X-Trace-Id
  • 日志 pattern 带 traceId/spanId,日志平台能按 traceId 聚合跨服务日志
  • 全项目没有裸 new Thread / Executors 裸线程池,线程池统一走 Bean + 装饰器
  • @Async 使用 Spring 管理的线程池,异步任务日志的 traceId 与主链路一致
  • MQ 生产者把 trace 上下文写入消息属性,消费侧能接上
  • 采样策略为"错误全量 + 正常低比例",采样率随容量定期复核
  • 客服工单模板包含 traceId 字段,报障入口标准化
  • 存量 Sleuth 项目迁移 Micrometer Tracing 前,回归验证过异步上下文传播