可观测性与稳定性 / 系统课时
排查 Trace 断链与上下文丢失
排查 Trace 断链与上下文丢失
Trace 断链通常表现为一次业务请求在后端被拆成多个 Trace,或下游 Span 变成新的根节点。排查关键是逐跳比较 trace_id、父 Span、traceparent 与采样标志,找出上下文在哪个边界被丢弃、重建或停止传播。
学习目标
- 用固定
traceparent判断断链发生在哪个服务或中间件边界 - 区分 Propagator 不一致、代理改写、异步上下文丢失与采样导致的“看似断链”
- 根据 Trace ID、Parent Span ID 和 sampled 标志验证修复结果
先确定断链发生在哪一跳
正常的跨服务调用中,Trace ID 应保持不变;每个新 Span 会获得自己的 Span ID,并把调用方当前 Span 作为父上下文。把客户端、服务 A、代理或网关、服务 B、消息生产者与消费者按实际路径列出来,逐跳记录入站和出站上下文,第一次出现新 Trace ID 的位置就是优先调查点。

如果 Trace ID 一直相同但某个 Span 不存在,不要立刻归因于传播失败,还要检查该服务是否创建了 Span、是否被采样,以及 Collector 或后端是否过滤。只有“从某一跳开始出现新的 Trace ID”才强烈指向提取失败或活动上下文丢失。
用固定 traceparent 做穿透探针
可以给入口请求注入一个已知的 W3C Trace Context,再沿调用链搜索这个固定 Trace ID。下面的 01 表示 sampled 标志已设置;<HOST>、<PORT>、<PATH> 用实际入口替换。
TRACE_ID=4bf92f3577b34da6a3ce929d0e0e4736
PARENT_SPAN_ID=00f067aa0ba902b7
curl -sS -o /dev/null -w 'http_status=%{http_code}\n' \
-H "traceparent: 00-${TRACE_ID}-${PARENT_SPAN_ID}-01" \
http://<HOST>:<PORT>/<PATH>预期输出
http_status=<VALUE><VALUE> 是应用实际返回的 HTTP 状态码,可能因测试接口而不同。随后在各服务日志、Collector 的受控 debug 输出或 Trace 后端中搜索固定的 TRACE_ID:正常情况下下游继续使用该 Trace ID,但会产生新的 Span ID;如果某一跳之后变成其他 Trace ID,检查该跳的入站提取和出站注入。
检查四类高频根因
第一类是 Propagator 不一致。W3C Trace Context 依赖 traceparent 与可选 tracestate;如果一端只发送 W3C,而另一端只解析 B3,就会生成新的根 Span。对支持标准环境变量的 SDK,可先显式统一传播与父级采样策略,再确认实际运行时确实读取了这些变量。
export OTEL_PROPAGATORS=tracecontext,baggage
export OTEL_TRACES_SAMPLER=parentbased_always_on
printf '%s\n' "$OTEL_PROPAGATORS" "$OTEL_TRACES_SAMPLER"预期输出
tracecontext,baggage
parentbased_always_on第二类是代理或网关处理 Header。未埋点的中间层应透明转发需要的追踪头;已埋点的网关可以创建自己的 Span,并向下游注入同一 Trace ID、以网关当前 Span ID 作为新的父上下文。重点检查的是 Trace ID 是否被清空或重建,而不是要求整个 traceparent 字符串逐字不变。
第三类是异步边界。线程池、回调、后台任务或手工创建并发任务时,如果活动 Context 没有被运行时或框架正确带过去,子操作会变成根 Span。消息系统则必须在发送时把 Context 注入消息属性,在消费时提取;批量消费多个独立消息时,必要时使用 Span Links 表达关联,而不是强行制造错误的单父子关系。
第四类是采样。ParentBased 策略会参考父上下文的 sampled 决策;上游未采样时,下游可能继续传播同一 Trace ID,却不导出对应 Span。此时是“数据不可见”,不是“上下文断了”,应同时核对入站 traceparent 最后一段标志、SDK sampler 配置与实际导出行为。
用父子关系与采样结果收口
修复后再次发送固定 traceparent 请求,并逐跳核对三个条件:Trace ID 从入口到下游保持一致;每个服务创建的新 Span 都指向正确的调用方父 Span;入口 sampled=1 时,受 ParentBased 控制的子 Span能够进入导出链路。若这三项成立而后端仍缺 Span,应转回数据导出路径排查,而不是继续修改传播配置。
最可靠的断链修复不是“看到一条完整瀑布图”,而是能解释每一跳为什么保留同一 Trace ID、为什么父 Span 发生预期变化,以及为什么采样决策与最终可见性一致。