Skip to content

分布式链路追踪:一条 trace 从哪来,为什么经常断在半路 ​

一、四条能自己验收的产出 ​

  • 能拆开一个 traceparent 头,说出四个字段各自的含义,并判断它是否合法
  • 能在四种跨协议场景里指出上下文在哪一跳丢失,并给出补法
  • 会为一个服务选择头部采样还是尾部采样,说得出另一半为什么不行
  • 能识别一个标签是高基数还是低基数,并解释它为什么会把存储打挂

版本前提:OpenTelemetry 规范(specification)最新版为 1.62.0(2026-10-22 发布),Collector 主干为 v0.165.x(v0.165.1 于 2026-11-09 发布),Java SDK 的 BOM 走到 1.68.0,Java 自动注入 agent 为 v2.33.1(2026-10-26)。规范和 SDK 的版本号是两套,别混着引用。W3C Trace Context 的正式推荐仍是 2021-11-23 那一版;Level 2 至今停留在 Candidate Recommendation Draft(2024-03-28),没有成为正式推荐——这意味着你可以在源码里看到 tracestate 的概率采样语义,但不要把它当成稳定契约来设计。

这些数字是截至 2026 年 11 月核对的,几周就变一轮,复核请看 OpenTelemetry 规范 与 W3C Trace Context。先记住一条贯穿全文的坐标:一条 trace 的完整程度取决于最弱的那一跳。

二、三支柱与它们在链路里的位置 ​

链路追踪不是"多打点日志",是把一次请求穿过多个进程的因果链显式记录下来。OpenTelemetry 想统一三件事:产生数据的 API、传输数据的协议、共享的上下文。

三支柱共享的是同一个上下文对象,不是同一份数据。Trace 回答"经过哪些环节、每段多久",Metric 回答"整体水位",Log 回答"那一步报了什么"。很多团队做了半年还是查不出问题,症结是把 trace 当日志用了——只看有没有错,不看结构。

先说清概念:Trace 是一棵 span 树,Span 是其中一个操作节点,Span Context 是能跨进程传递的最小子集。只有 Span Context 进 HTTP header,其余属性留在本地导出。

三、导入案例:一条只有两跳的 trace ​

2026 年 7 月,一个做跨境结算的系统上线链路追踪。验收时图很漂亮,网关 → 订单 → 结算 → 银行网关四层都在。一周后出故障,打开追踪只剩"网关 → 订单"两跳。

排查过程:先确认结算服务收到了请求——日志里有,还打了 trace ID。再对比两边 ID——不一样。定位到订单调结算走的是消息队列而非 HTTP:HTTP 客户端那侧注入了上下文,消息生产者那侧没人管,消息发出去就断了。

问题不在功能,在没人意识到"传播"要针对每种传输介质单独做。SDK 自动注入只覆盖它认识的协议。

四、traceparent 到底长什么样 ​

W3C 规定的头格式是固定的四段:

text
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
             ^  ^                                ^                ^
             |  |                                |                └─ trace-flags,01 表示 sampled
             |  |                                └────────────────── parent-id(16 位十六进制)
             |  └─────────────────────────────────────────────────── trace-id(32 位十六进制)
             └────────────────────────────────────────────────────── version,当前为 00

三件事容易记错。第一,version 目前只有 00 被定义,收到不认识的版本要按规范忽略。第二,trace-id 与 parent-id 全零都非法,老 SDK 在上下文缺失时会写出全零,这类头必须拒绝。第三,trace-flags 的 bit 0 是 sampled,判断采样要用按位与,不能写 flags == 1。

OTel 默认传播器就是这套 W3C 头,另有 tracestate 携带厂商私有信息,键值对、有顺序、最多 32 个成员。

java
// 预期输出:传入的 traceparent 被解析,parent 的 traceId 与 header 一致
// 依赖:io.opentelemetry:opentelemetry-api(BOM 1.68.0)
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.context.Context;
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.context.propagation.TextMapGetter;

TextMapGetter<Map<String, String>> getter = new TextMapGetter<>() {
    @Override public Iterable<String> keys(Map<String, String> carrier) {
        return carrier.keySet();
    }
    @Override public String get(Map<String, String> carrier, String key) {
        return carrier.get(key);
    }
};

Map<String, String> headers = Map.of(
    "traceparent", "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");

Context ctx = GlobalOpenTelemetry.getPropagators().getTextMapPropagator()
        .extract(Context.root(), headers, getter);
SpanContext sc = Span.fromContext(ctx).getSpanContext();

System.out.println(sc.getTraceId());   // 4bf92f3577b34da6a3ce929d0e0e4736
System.out.println(sc.getSpanId());    // 00f067aa0ba902b7
System.out.println(sc.isSampled());    // true

如果 System.out.println(sc.getTraceId()) 打印出 32 个 0,说明传播器没读到合法的头,它会给你一个无效上下文而不是报错。这是最容易漏的验收点:不报错,但也没有上下文。

五、传播断在哪:四种典型场景 ​

自动注入只覆盖它认识的协议。下面四种是我们实际断过的,补法各不相同。

场景断在哪补法
HTTP 同步调用自定义客户端没走标准库手动注入 header,或换用被支持的客户端
消息队列生产者不注入、消费者不提取把上下文放进消息属性,两端各写一次
线程池 / 异步回调跨线程时 Context 没跟着走提交任务时捕获 Context 再在子线程 attach
定时任务 / 批处理没有上游,天然是新 trace 的起点显式建 root,不要用父上下文
java
// 预期输出:子线程里的 traceId 与提交任务时一致;没包这一层会是 32 个 0
import io.opentelemetry.context.Context;
import io.opentelemetry.context.Scope;
import java.util.concurrent.ExecutorService;

ExecutorService pool = java.util.concurrent.Executors.newFixedThreadPool(8);
Context parent = Context.current();   // 提交时的上下文

pool.submit(() -> {
    try (Scope ignored = parent.makeCurrent()) {
        // 这里打日志或建 span,都会挂到同一个 trace 上
    }
});

跨线程这条要特别强调,它是唯一"测试环境永远对、生产环境经常错"的坑。单机压测线程复用少,问题不显形;上生产线程池一忙,父子上下文就开始串。我们后来包了个装饰器,往线程池提交的任务强制带上下文。

两个常见的想当然:一是以为上下文传播框架自动做好了,实际只覆盖它认识的几种协议,消息队列、自定义 TCP 客户端、异步回调都得自己接;二是以为两端 trace ID 一样就接上了,实际 parent-id 错位一样能把树画歪。

六、采样:头部和尾部不是二选一 ​

采样是链路追踪里最需要判断力的部分。官方口径很直接:流量里绝大部分是健康请求时不需要 100% 的 trace,量化门槛是每秒 1000 条以上才值得认真考虑采样。

头部采样最常见的形式是一致性概率采样:拿 trace ID 做哈希,按比例决定采不采。优点是简单、无状态、管道任何位置都能做。致命缺点是看不到整条 trace——后来会报错的请求在入口时和正常请求一模一样。

尾部采样(tail sampling)把决定推迟到收齐大部分 span 之后,于是可以写"凡是含错误的必然保留"、"凡是超过 2s 的必然保留"这种规则。代价是它必须有状态、必须缓冲。Collector 的 tail sampling processor 目前状态是 beta,文档里有一句要划重点的话:同一条 trace 的所有 span 必须送到同一个 Collector 实例。这意味着扩容时你要在前面加一层负载均衡导出器做按 trace ID 路由,而不能简单加副本。

yaml
# otelcol 配置:两级管道,前级按 trace ID 均衡,后级做尾部采样
# 预期:同一条 trace 的所有 span 落到同一个 tail sampling 实例
receivers:
  otlp:
    protocols:
      grpc: { endpoint: 0.0.0.0:4317 }

processors:
  batch: {}
  tail_sampling:
    decision_wait: 10s
    num_traces: 100000
    policies:
      - name: errors-always
        type: status_code
        status_code: { status_codes: [ERROR] }
      - name: slow-requests
        type: latency
        latency: { threshold_ms: 2000 }
      - name: baseline
        type: probabilistic
        probabilistic: { sampling_percentage: 3 }

exporters:
  otlp/jaeger:
    endpoint: jaeger-collector:4317
    tls: { insecure: true }

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, tail_sampling]
      exporters: [otlp/jaeger]

decision_wait 与 num_traces 要一起调。前者是等多久做决定,后者是内存里最多放多少条 trace。接收速度超过决定速度时,环形缓冲把最老的 trace 挤掉,sampling_trace_dropped_too_early 会往上涨——那是"没轮到判断就被丢了"。

我不建议在流量低于每秒两百条 trace 的系统上做尾部采样。 官方文档明确列了不该采样的情形:数据量很小、只用聚合数据、或者受监管限制不允许丢数据。这个规模下尾部采样的固定成本(额外一层 collector、有状态、要监控缓冲)大于它省下来的存储费,而且小流量下"每条错误都保留"靠头部采样加错误日志就够了。

头部和尾部也不是互斥。官方给的做法是先头部采样把流量压到可控范围,再在管道后段做尾部决策,保护管道本身不被冲垮。

还有个误解:以为采样率可逆——"先采 1%,不够再调回来"。调不回来。被丢掉的 span 没存过,调到 100% 也只能拿到此刻起的数据。采样比例属于容量规划,不是当天排障的手段。

七、后端选型:Jaeger 2 还是 Tempo 3 ​

两个项目在 2026 年的形态和几年前很不一样。Jaeger v2 于 2024 年 11 月发布,构建在 OpenTelemetry Collector 框架之上,处理管道就是 collector 管道,配置语法一致,最新 2.23.0(2026-11-05)。Tempo 最新 3.1.1(2026-10-21):所有 trace 存对象存储,微服务模式下用 Kafka 兼容队列当 WAL,写路径副本因子可做 1,块用 Parquet 列式存储。

维度Jaeger 2Tempo 3
存储Cassandra / ClickHouse / Elasticsearch / OpenSearch / Badger 等主要对象存储,Parquet 块
查询语言依赖所选存储的检索能力TraceQL
部署重心与 Collector 同构,配置复用读写路径分离,独立扩缩
成本结构取决于后端存储选型对象存储为主,通常更省
适合已有 ES/ClickHouse 技术栈已有对象存储 + Grafana 体系

我的判断:如果你已经在用 Grafana,选 Tempo;如果你已经在用 Elasticsearch 或 ClickHouse 并且团队熟,选 Jaeger 2。 存储选型不是性能问题,是运维能力问题——你得有人能在半夜修那个存储。

顺带说一个容易忽略的:OTel 的 Profiles 信号状态仍是 Alpha,截至 2026 年 11 月不建议作为生产依赖。三支柱先做扎实,别急着上第四个。

八、高基数标签:把后端打挂的那一类 ​

高基数指某个标签的取值数量随流量线性增长。user_id、order_id、request_id、完整 URL 都是典型高基数。它们进 span attributes 后,后端要为每个取值建索引,最终不是慢,是写不进去。

治理的办法不是"少打标签",是分层。低基数的留在 span 上(http.request.method、http.response.status_code、http.route);高基数的要么进日志,要么进 baggage 但要明确知道它会跟着每个请求传;真正需要按高基数检索的,放日志或专门的分析存储。

yaml
# 在 Collector 侧做最后一道过滤:删掉已知的高基数标签
# 预期:导出到后端的 span 里不再出现 user.id / order.id
processors:
  attributes/scrub:
    actions:
      - key: user.id
        action: delete
      - key: order.id
        action: delete
      - key: http.url
        action: delete      # 完整 URL 含查询参数,基数极高

http.route 和 http.url 的差别值得单独记一下。语义约定里,span 名字的 target 应该优先用 http.route(服务端,即路由模板如 /orders/{id}),客户端侧才用 url.template;规范明确写了 url.full 必须是重定向之前的原始绝对 URL。如果你把完整 URL 当标签打,等于把每个订单号都变成了一个维度。

治理动作要落在采集侧而不是后台侧,这一点经常被做反。等到数据已经写进后端再去清理,成本是两件事:重写索引,和接受一段时间的查询变慢。我们在 Collector 里加 attributes/scrub 之后,单个 span 的平均序列化体积从 3.1KB 降到 1.2KB,后端存储日增量下降约六成——这个数字只在我们的字段分布下成立,你们的比例会不同,但方向不会变。

九、三道需要动手的题 ​

三道题:

  1. 一个用 Spring Boot 4.1 写的服务,HTTP 入口有 trace,调用下游的 Feign 客户端没有。不写代码的情况下,你先查什么?
  2. 你的尾部采样配了"错误全留",但线上错误 trace 的采样率只有 40%。可能是哪三种原因?
  3. 有人说"我们把采样率从 10% 调到 1%,存储降了 90%,说明追踪没用"。这句话错在哪?

十、这一节要记住的词 ​

术语英文一句话解释
跨度span一次操作的记录,含起止时间、属性和父子关系
跨度上下文span context能跨进程传递的最小子集:trace ID、span ID、flags
上下文传播context propagation把上下文序列化进传输介质、对端再还原的机制
头部采样head sampling请求入口就决定采不采,无状态但看不到全貌
尾部采样tail sampling收齐 span 后决定,有状态但能按错误和延迟判断
高基数high cardinality标签取值数量随流量增长,索引成本不可控
行李baggage随请求传播的键值对,不进入 span 但会跟着走

最后一件事说清楚:本篇的版本号和参数默认值于 2026 年 11 月 16 日核对官方仓库与文档。trace-context Level 2 的状态、尾部采样的 beta 标记、Collector 的 num_traces 默认值都还在变,动手前请在你锁定的版本上再确认一次。

三个可以用来自查的判断,比记住版本号有用:一条断掉的 trace 里,断点永远在"两种介质交界处",从不在某个进程内部;采样率只能往下调、不能往上调回来,所以它属于容量规划;高基数治理只能做在采集侧,事后治理的成本是前者的十倍以上。

还有一条是写给验收人的:如果你的追踪系统上线三个月,从没有一次靠它定位到问题,那不是团队不用,是链路断在你没测过的那一跳。先去数一数断链,再谈采样率和存储成本。