分布式追踪中 Span 与 Trace 设计原理

可视化演示

展示OpenTelemetry Span结构、Trace上下文跨服务传播、采样策略与AI推理管道追踪，切换模式掌握分布式可观测性核心原理。

核心概念：什么是 Trace 与 Span

一单从杭州发往东京的包裹，会依次经过揽收站、分拨中心、海关、海外仓、派送员之手。每个站点都会在系统里生成一条“处理记录”，写明当前时间、耗时、是否正常。这些记录放在一起，就是包裹的完整旅程。在分布式系统里，一次用户请求（比如点击“下单”）同样会穿梭于网关、商品、支付、数据库等多个服务之间。把整条调用路径上所有处理记录按先后顺序拼起来，就得到了 Trace；而其中某一次具体处理——例如“调用支付服务花了 200 毫秒”——就是一个 Span。Span 是构成 Trace 的最小工作单元，相当于快递在某个站点的一次“收件—处理—发出”的回执。

一个 Span 至少包含：操作名称 name、全局唯一的 spanId、指向父级记录的 parentId、开始与结束时间戳 start/end、业务标签 attributes、结果状态 status。Trace 则是这些 Span 按调用关系组成的有向无环图，通常呈现为一棵树。无论一次请求经过了多少个服务，只要它们携带同一个 traceId，就能被还原成一条完整的调用链。

有了这张“总运单”（traceId）和每一站的耗时记录（duration），工程师就能像客服查快递一样，精确回放整条请求的每一段旅程。

链路构建：父子关系与树形结构

快递分拣是层层拆单的：杭州总部生成一张干线单，干线单到达分拨中心后拆成若干派送单，派送单再交给快递员。每一张下级单据都必须填写“上一级单据号”，这样任何一张回执都能追溯到它的上级。Span 之间的父子关系正是这样建立的：网关作为入口生成根 Span，调用商品服务时生成子 Span，商品服务再查询数据库又生成孙 Span。每个子 Span 的 parentId 精确指向父 Span 的 spanId，层层挂接。

当所有携带同一 traceId 的 Span 都到达追踪后端后，系统按照 parentId 把它们组织成一棵树。树的根是请求入口处的根 Span；层数越深表示调用链越长；同一父节点下的多个子节点，则代表并行发起的不同调用。整棵树的形状，就是一次请求在微服务网络中的真实足迹。

如同快递单据层层关联一样，parentId 让散落各处的回执单有了归属，工程师得以从根节点一路查到叶子节点。

上下文传播：把“运单号”传递给下一个服务

包裹从一个站点转运到下一个站点时，交接的第一件事就是扫描运单号。运单号永远跟着包裹走，下一站的记录才能挂到同一趟旅程上。微服务之间同样需要传递这种“运单号”——只是进程之间不共享内存，必须通过通信协议把 traceId 和 parentId 带给下一个服务。这个动作在分布式追踪里叫作 上下文传播（Context Propagation）。

最常见的传播介质是 HTTP 请求头。W3C 制定了 Trace Context 标准，其中定义了 traceparent 请求头：当服务 A 调用服务 B 时，A 会把当前 Span 的信息写进请求头；B 解析这个请求头，在自己的进程里创建子 Span，并把 A 的 traceId 与 A 的 spanId 记录为父关系。消息队列场景则把 traceparent 放进消息属性，gRPC 则放入 metadata，机制完全一致。

就像交接单必须随包裹走一样，traceparent 必须跟着每一次 RPC 或消息传递走，链路才能在跨进程的边界上不断延伸。

采样策略：不是每一单都要全程稽核

快递公司不会对每一单包裹都做“全程视频稽核”，那样成本高到无法承受。更常见的做法是随机抽取 2%～10% 的运单做重点核查，同时对用户投诉的单子 100% 核查。分布式追踪面临同样的成本问题：高流量系统如果全量记录每个请求的每个 Span，存储和 CPU 开销会迅速吞噬服务资源。采样（Sampling） 就是决定“哪一单要全程记录”的策略。

最简单的策略是固定采样率：每个新请求到达时，生成一个 0 到 1 之间的随机数，小于设定阈值 r 就记录整条链路。更精细的策略还有头部采样和尾部采样：头部采样在请求刚进入系统时就做出决定，实现简单但无法预知请求是否会失败；尾部采样先把少量数据缓存在内存中，等请求结束后根据结果决定是否保留，因此能确保所有错误请求都不被遗漏。动态采样则根据当前流量高低自动调整 r，流量低谷时多记录，高峰时少记录。

抽样稽核让快递公司用可控成本覆盖流程监督；采样则让追踪系统在高流量下仍然经济可用，把宝贵资源留给真正值得分析的请求。

标准规范：快递业为何需要统一面单

早年间各家快递公司各用一套运单号，跨公司转运时系统无法互认，对账全靠人工。后来国家邮政推动统一面单规范，条形码一扫码就能识别出快递公司、运单号与包裹状态，整个网络才真正联通。微服务的可观测性领域也曾经历过这种“格式混乱”：Jaeger、Zipkin、SkyWalking 各定义各的数据模型，业务方每换一个监控后端就要改一遍埋点代码。

OpenTelemetry（简称 OTel） 就是可观测性领域的“统一面单标准”。它是一个由 CNCF 维护的开源标准，提供统一的 API、SDK 与传输协议（OTLP）。应用只需按 OTel API 埋一次点，数据就可以导出到 Jaeger、Prometheus、SkyWalking 等任意兼容后端；其 traceparent 格式与 W3C Trace Context 标准保持一致，保证了跨厂商互认。OTel 的架构分为三层：API 层定义埋点接口，SDK 层实现采样、导出等逻辑，Exporter 层负责把数据发往具体后端。

统一面单让任何两家快递公司都能互认包裹；OTel 则让任何服务的追踪数据都能无障碍汇入统一的可观测性平台。

实践应用：链路分析与性能定位

当客户投诉“包裹三天没动”时，客服会打开全链路时间轴，逐站查看哪一段耗时异常——是卡在海关清关，还是派送员迟迟未取件。这套“查每一站耗时”的思路，正是分布式追踪最核心的实践价值。在后端系统中，追踪平台会把一条 Trace 绘制成瀑布图：纵轴是 Span 树，横轴是时间，每个 Span 是一条横条，长度代表耗时。哪根横条最长，瓶颈就一目了然。

在 AI 推理场景中，这种能力尤其宝贵。假设一个 LLM 应用的“首 Token 延迟”飙到了 10 秒，传统手段只能逐服务看日志猜原因；瀑布图则会直接显示：认证耗时 300ms、RAG 检索耗时 6.5s、模型推理仅 1.2s。矛头立刻指向 RAG 检索中的向量召回环节。除了人工看图，还可以用算法定位：在关键路径上找到耗时最长的 Span 作为首要优化目标，再结合百分位数值（如 p99，即 99% 的请求耗时都低于该值）评估波动。

客服按站点耗时锁定了“卡在海关”；工程师按瀑布图锁定“卡在检索”。可观测性的终极价值，就是把抽象的网络延迟还原成一条条可定位的因果链。

设计要点：把面单填规范，链路才有用

经验丰富的快递员面单填写很有讲究：环节名写清楚、时间戳精确到秒、异常情况必填备注，同时面单上收件人电话的中间四位会被隐去。不规范的填写会让后续对账寸步难行。Span 的埋点设计同样遵循这些原则。首先是粒度控制：建议把一个 Span 对齐到一次有业务意义的动作——一次 RPC 调用、一次数据库查询、一次模型推理；而不是在 for 循环里每迭代一次就创建一个 Span，否则链路会膨胀成噪音。

其次是开销控制：每个 Span 从创建、序列化到传输、存储都有成本，采样可以在入口处兜底，但埋点本身也要克制。第三是异常处理：失败的 Span 必须标记错误状态并附上原因，否则“快”与“慢”的对比失去了参照。最后是安全脱敏：不要把 Prompt 全文、Token、手机号等敏感信息写进 Span 的 attributes，它们会随着链路数据进入日志与监控平台，形成泄露风险。

面单填得规范，全网的包裹才能高效流转；Span 设计得规范，整条链路才能在排障时真正派上用场。

AI 应用场景

Python 演示

# -*- coding: utf-8 -*-"""简易分布式追踪模拟：Span/Trace 与上下文传播""" import randomimport timeimport uuid  class Span:    """一个 Span 代表一次操作单元，类似快递的一个站点回执"""     def __init__(self, name, trace_id, parent_id=None):        self.name = name        self.trace_id = trace_id        self.parent_id = parent_id        self.span_id = uuid.uuid4().hex[:16]        self.start_time = None        self.end_time = None     def start(self):        self.start_time = time.time()     def finish(self):        self.end_time = time.time()     def duration_ms(self):        if self.start_time is None or self.end_time is None:            return 0        return int((self.end_time - self.start_time) * 1000)     def to_traceparent(self):        parent = self.parent_id or self.span_id        return "00-{}-{}-01".format(self.trace_id, parent)  class Trace:    """一个 Trace 代表一次完整请求的调用链"""     def __init__(self, sample_rate=0.8):        self.sample_rate = sample_rate        self.sampled = random.random() < sample_rate        self.trace_id = uuid.uuid4().hex[:32]        self.spans = []     def new_span(self, name, parent_id=None):        if not self.sampled:            return None        span = Span(name, self.trace_id, parent_id)        self.spans.append(span)        return span  def simulate_request():    trace = Trace(sample_rate=0.8)    root = trace.new_span("api-gateway")    if root is None:        print("本次请求未采样，不记录链路")        return    root.start()    time.sleep(0.05)     order = trace.new_span("order-service", parent_id=root.span_id)    order.start()    time.sleep(0.03)     db = trace.new_span("db-query", parent_id=order.span_id)    db.start()    time.sleep(0.08)    db.finish()    order.finish()    root.finish()     print("traceId =", root.trace_id)    print("传递的 traceparent =", root.to_traceparent())    for s in trace.spans:        print("- {} spanId={} parentId={} duration={}ms".format(            s.name, s.span_id, s.parent_id, s.duration_ms()))  if __name__ == "__main__":    simulate_request()

1. self.sampled = random.random() < sample_rateTrace 创建时根据采样率决定是否记录，相当于快递公司决定这一单要不要全程稽核。
2. span = Span(name, self.trace_id, parent_id)新 Span 绑定全局 traceId 与父 Span 的 spanId，回执单挂到了正确的旅程上。
3. self.span_id = uuid.uuid4().hex[:16]每个 Span 生成独立的 16 位十六进制 ID，作为自己在树上的唯一身份。
4. return "00-{}-{}-01".format(self.trace_id, parent)序列化 W3C traceparent 头，下游服务解析后即可接力续写链路。
5. trace.new_span("db-query", parent_id=order.span_id)孙 Span 通过 parent_id 指向父 Span，树形结构由此生长。
6. s.duration_ms()计算每个 Span 的净耗时，对应瀑布图中横条的长度。

常见误区

面试题