分布式链路追踪:一条 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 规定的头格式是固定的四段:
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 个成员。
// 预期输出:传入的 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,不要用父上下文 |
// 预期输出:子线程里的 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 路由,而不能简单加副本。
# 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 2 | Tempo 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 但要明确知道它会跟着每个请求传;真正需要按高基数检索的,放日志或专门的分析存储。
# 在 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,后端存储日增量下降约六成——这个数字只在我们的字段分布下成立,你们的比例会不同,但方向不会变。
九、三道需要动手的题
三道题:
- 一个用 Spring Boot 4.1 写的服务,HTTP 入口有 trace,调用下游的 Feign 客户端没有。不写代码的情况下,你先查什么?
- 你的尾部采样配了"错误全留",但线上错误 trace 的采样率只有 40%。可能是哪三种原因?
- 有人说"我们把采样率从 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 里,断点永远在"两种介质交界处",从不在某个进程内部;采样率只能往下调、不能往上调回来,所以它属于容量规划;高基数治理只能做在采集侧,事后治理的成本是前者的十倍以上。
还有一条是写给验收人的:如果你的追踪系统上线三个月,从没有一次靠它定位到问题,那不是团队不用,是链路断在你没测过的那一跳。先去数一数断链,再谈采样率和存储成本。