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

2. 分布式追踪基础：Trace、Span、SpanContext 核心概念，OpenTelemetry 标准与数据模型

在值班台故障排查场景中，分布式追踪是定位跨服务请求异常的“第一性原理”。理解 Trace、Span、SpanContext 三大核心概念，以及 OpenTelemetry 标准下的数据模型，是构建高效追踪体系的前提。本节从值班工程师的视角出发，拆解这些抽象概念与日常排障动作的对应关系。

2.1 核心概念：Trace、Span、SpanContext

分布式追踪的本质是记录一个请求在多个服务节点间的完整执行路径。三个核心概念构成了追踪数据的骨架：

概念	定义	值班排障中的对应物
Trace	一个完整请求的生命周期，从入口到所有下游返回，由一组具有相同 TraceID 的 Span 组成的有向无环图（DAG）。	一次用户下单请求的完整调用链，包含网关、订单、支付、库存等所有节点。
Span	Trace 中的一个工作单元，记录一个操作（如 RPC 调用、数据库查询）的开始、结束、状态和元数据。	“订单服务调用支付服务”这一单次远程调用，包含耗时、状态码、异常堆栈。
SpanContext	跨进程传递的追踪标识集合，包含 TraceID、SpanID、TraceFlags、Tracestate，用于在服务间串联调用关系。	HTTP 请求头中的 `traceparent` 字段，是下游服务识别“我是谁的上游”的唯一凭证。

值班提示： 当你在追踪系统中看到“断链”或“孤儿 Span”时，90% 的原因是 SpanContext 在跨服务传递时丢失或格式错误。优先检查网关和消息队列的透传配置。

2.2 Trace 与 Span 的层次结构

一个 Trace 由多个 Span 组成，Span 之间通过 Parent-Child 关系形成树状结构。根 Span（Root Span）代表请求的入口，没有父 Span。每个 Span 记录其父 SpanID，从而构建出完整的调用拓扑。

  关键关系：
  一个 Trace 有且仅有一个 Root Span。
每个 Span 有唯一的 SpanID，并记录其 ParentSpanID。
同一 Trace 内的所有 Span 共享同一个 TraceID。
Span 可以嵌套（同步调用）或并列（异步扇出）。

2.3 SpanContext：跨服务传递的“信使”

SpanContext 是分布式追踪的“粘合剂”。它不包含业务数据，只携带路由和标识信息，通过 HTTP 头、gRPC 元数据或消息队列属性在服务间传递。OpenTelemetry 标准化的 W3C Trace Context 协议定义了 traceparent 和 tracestate 两个头部。

字段	格式	示例	作用
TraceID	16 字节，32 位十六进制	`0af7651916cd43dd8448eb211c80319c`	全局唯一标识一次 Trace
SpanID	8 字节，16 位十六进制	`b7ad6b7169203331`	标识当前 Span
TraceFlags	1 字节，8 位	`01`（采样标记）	控制追踪行为（如是否采样）
Tracestate	键值对列表	`vendor=example:key=value`	携带供应商自定义的追踪上下文

常见陷阱： 当使用异步消息（Kafka/RabbitMQ）或 gRPC 流时，SpanContext 不会自动透传。必须在生产者发送消息前手动注入，消费者接收消息后手动提取。否则会出现“跨进程断链”，导致 Trace 被拆成多个孤立片段。

2.4 OpenTelemetry 标准与数据模型

OpenTelemetry（OTel）是 CNCF 的观测性标准，统一了分布式追踪、指标和日志的采集规范。在追踪领域，OTel 定义了 Trace SDK、OTLP 协议 和 语义约定，确保不同语言、不同厂商的追踪数据可以互操作。

2.4.1 OTel 追踪数据模型核心结构

OTel 的 Span 数据模型比传统 Dapper 模型更丰富，增加了 Attributes、Events、Links 和 Status 等字段，便于值班工程师在排障时快速定位根因。

字段	类型	说明	排障场景示例
SpanId	string	当前 Span 唯一标识	用于关联日志中的 span_id 字段
ParentSpanId	string	父 Span 标识，空值表示 Root Span	判断调用层级，定位“谁调用了谁”
TraceId	string	所属 Trace 标识	聚合所有相关 Span 的过滤条件
Name	string	Span 名称，通常为操作描述	`POST /api/payment/charge`
Kind	enum	Span 角色：Client/Server/Internal/Producer/Consumer	区分是客户端调用还是服务端处理
StartTime / EndTime	timestamp	开始与结束时间戳	计算耗时，识别慢调用
Attributes	map<string, any>	键值对元数据，描述 Span 上下文	`http.status_code=500`, `db.system=mysql`
Events	list<Event>	Span 生命周期内的带时间戳事件	记录异常堆栈、缓存命中/未命中
Links	list<Link>	关联其他 Trace 的 Span	连接异步消息的生产者和消费者
Status	StatusCode + Description	Span 执行结果：Unset/Ok/Error	快速筛选失败 Span

2.4.2 OTel 语义约定（Semantic Conventions）

OTel 为常见技术栈（HTTP、gRPC、数据库、消息队列）定义了标准化的 Attribute 键名，避免不同团队使用“方言”。值班工程师在查询追踪数据时，可以依赖统一的字段名进行过滤。

  常用语义约定示例：
  http.method — HTTP 方法（GET/POST）
http.status_code — HTTP 响应状态码
db.system — 数据库类型（mysql/redis/mongodb）
messaging.system — 消息队列类型（kafka/rabbitmq）
rpc.service — gRPC 服务名
error.type — 异常类型（java.lang.NullPointerException）

2.5 值班排障中的实际应用

理解上述概念后，值班工程师在追踪系统中可以执行以下标准操作：

按 TraceID 聚合： 从用户报障的请求 ID 或日志中提取 TraceID，查询完整调用链。
识别 Root Span： 找到 ParentSpanId 为空的 Span，确认请求入口和整体耗时。
筛选 Error Status： 在 Span 列表中过滤 Status.Code = Error 的 Span，快速定位失败节点。
检查 Attributes： 查看失败 Span 的 http.status_code、error.type 等属性，判断是业务错误还是系统异常。
分析 Events： 展开 Span 的 Events 列表，查看异常堆栈或关键日志时间戳。
验证 SpanContext 传递： 如果出现断链，检查上下游服务的 traceparent 头部是否一致。

值班口诀： “Trace 找全链，Span 看耗时，Context 查断点，Attributes 定根因。” 掌握这四步，80% 的分布式故障可以在 5 分钟内定位。