📚 课程目录第2章分布式追踪基础

2. 分布式追踪基础：Trace、Span、SpanContext 的核心概念与关系

在深入探讨 Span 标签标准化之前，必须首先建立对分布式追踪三大核心抽象——Trace（追踪）、Span（跨度）和 SpanContext（跨度上下文）——的精确理解。这三者构成了所有分布式追踪系统的数据模型基石，也是后续 MTTR 复盘口径设计的逻辑起点。

2.1 核心概念定义

概念	定义	类比（一次电商下单）	MTTR 复盘价值
Trace	代表一个完整的、端到端的请求处理流程，贯穿分布式系统中的多个服务或组件。由一组具有相同 TraceID 的 Span 组成。	用户从点击“提交订单”到收到“下单成功”的完整过程。	界定故障影响范围：一个 Trace 失败意味着一次用户请求受损。
Span	Trace 中的最小工作单元，代表一个服务内部或服务间的一次具体操作（如 RPC 调用、数据库查询、消息队列发送）。每个 Span 记录开始时间、结束时间、状态及标签。	订单服务调用库存服务扣减库存的这一次 RPC 调用。	定位故障根因：通过分析耗时异常或错误状态的 Span，快速锁定问题服务或操作。
SpanContext	Span 的元数据载体，负责在分布式环境中跨进程传递追踪上下文。核心字段包括 TraceID、SpanID、Baggage Items（透传数据）。	快递包裹上的运单号（TraceID）和当前站点编号（SpanID），以及随包裹附带的特殊备注（Baggage）。	保证追踪链路完整性：SpanContext 传播失败会导致链路断裂，增加复盘难度。

MTTR 复盘要点： 在复盘过程中，Trace 是“事故现场全景图”，Span 是“关键证据点”，SpanContext 是“证据链的粘合剂”。任何一环的缺失或错误，都会导致复盘结论的偏差。

2.2 三者关系：树形结构与传播机制

Trace、Span 与 SpanContext 之间的关系可以用一个树形结构来精确描述。一个 Trace 是一棵由 Span 组成的树，根 Span 代表入口请求，子 Span 代表下游调用。SpanContext 则沿着这棵树的边进行传播。

2.3 Span 的生命周期与关键属性

理解 Span 的生命周期是进行标签设计的前提。一个 Span 从创建到结束，经历以下阶段，每个阶段都对应着可观测性数据的采集点。

Span Start（开始）：记录开始时间戳（Start Time），创建 SpanContext。
Span Operation（操作执行）：执行具体的业务逻辑或 RPC 调用，期间可以添加 Tags（标签） 和 Logs（日志）。
Span Finish（结束）：记录结束时间戳（End Time），计算耗时（Duration），设置状态（OK / Error）。
Span Export（导出）：将 Span 数据异步上报到后端存储（如 Jaeger、Zipkin、OpenTelemetry Collector）。

属性	说明	MTTR 复盘用途
TraceID	全局唯一标识，关联同一 Trace 下的所有 Span。	快速检索完整调用链，还原故障现场。
SpanID	当前 Span 的唯一标识。	精确定位到具体的故障 Span。
ParentSpanID	父 Span 的 SpanID，用于构建树形结构。	分析调用层级，判断故障是根因还是被波及。
Operation Name	Span 的操作名称，如 `/api/order/create`。	按操作聚合分析，发现高频故障点。
Start / End Time	Span 的开始和结束时间戳。	计算耗时，识别慢调用和延迟峰值。
Status	Span 的执行状态：OK、Error 或 Unset。	快速筛选出所有失败的 Span，缩小排查范围。
Tags / Attributes	键值对形式的元数据，如 `http.status_code=500`。	提供故障上下文，是 MTTR 复盘的核心数据来源。

常见陷阱： 在复盘时，如果发现 Trace 链路不完整（例如缺少中间 Span），首先要检查 SpanContext 传播是否正常。常见的传播失败原因包括：HTTP 头被代理服务截断、异步消息队列未正确传递 Context、线程池切换导致上下文丢失。这些都会导致复盘时出现“断链”，增加 MTTR。

2.4 从概念到实践：一个 Trace 的完整旅程

为了将上述概念串联起来，我们通过一个典型的微服务调用场景来展示 Trace、Span 和 SpanContext 如何协同工作。

  复盘案例： 假设上述 Trace 中，库存服务返回了错误。通过查询 TraceID T-123，我们可以立即看到：

  - 根 Span（API 网关）状态为 OK，说明入口正常。

  - 订单服务 Span 状态为 Error，且 Tags 中包含 error.message=inventory insufficient。

  - 库存服务 Span 状态为 OK，但返回了业务错误码。

  结论： 故障根因是订单服务对库存服务返回的业务错误处理不当，而非库存服务本身崩溃。这避免了盲目重启库存服务的错误操作，直接缩短了 MTTR。

2.5 核心关系总结

Trace 是 Span 的集合：一个 Trace 由多个 Span 组成，这些 Span 通过 TraceID 关联，形成一棵有向无环图（DAG）。
Span 是 Trace 的节点：每个 Span 代表一个独立的工作单元，是数据采集和标签挂载的基本单位。
SpanContext 是 Span 的纽带：它负责在分布式环境中传递 TraceID 和 SpanID，确保所有 Span 能够被正确关联到同一个 Trace 上。
标签（Tags）是 Span 的语义化扩展：Tags 是附加在 Span 上的键值对，用于描述 Span 的上下文信息（如 HTTP 状态码、数据库语句、错误堆栈）。这正是我们后续课程要标准化的核心对象。