📚 课程目录第3章分布式追踪原理

3. 分布式追踪原理

在支付链路中，一笔交易往往要穿过网关、风控、账务、渠道适配、银行接口等十几个服务。当用户反馈“扣款成功但订单未更新”时，如果没有统一的追踪模型，排查只能靠逐台机器翻日志，效率极低。分布式追踪的核心，就是用一套标准化的数据模型，把一次交易在多个进程中的执行过程串成一条可检索、可还原的链路。理解这套模型，是后续做交易定位的前提。

一、核心原理：Trace、Span与两个ID

分布式追踪的最小数据单元是 Span（跨度），它表示一次具体的操作，例如“调用风控接口”“执行数据库更新”。每个 Span 记录操作名称、开始时间、持续时长、状态、属性标签以及与其他 Span 的关系。一次完整请求所关联的所有 Span 构成一棵树，这棵树就是 Trace（追踪）。

标识这两个概念的是两个关键字段：

TraceID：全局唯一，标识一整条链路。同一次交易的所有 Span 共享同一个 TraceID，它是交易定位的第一检索键。
SpanID：标识单个 Span，在 Trace 内唯一。通过 parentSpanID 指向父 Span，从而还原调用层级。

可以把 Trace 理解为一次交易的“档案袋”，TraceID 是档案编号，Span 是袋中的每一张操作记录，SpanID 是记录编号，parentSpanID 则说明这张记录由谁触发。支付场景中，TraceID 通常由入口网关生成，并贯穿整条链路。

关键点：TraceID 决定“能不能找到这笔交易”，SpanID 与父子关系决定“能不能还原这笔交易在每一步发生了什么”。

二、上下文传播：让链路跨进程不断裂

Span 之间要形成父子关系，就必须把追踪上下文从一个服务传递到下一个服务。这个上下文至少包含 TraceID、当前 SpanID 和采样标记。传播方式分为两类：

进程内传播：通过线程本地变量（如 Java 的 ThreadLocal）或上下文对象，在同一进程的调用栈中传递。
跨进程传播：通过协议头在服务间传递。HTTP 常用 traceparent 头，消息队列则把上下文写入消息属性。

W3C Trace Context 标准定义的 traceparent 格式如下：

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
             │  │                                │                │
             │  │                                │                └─ 采样标记(01=采样)
             │  │                                └─ 当前 SpanID
             │  └─ TraceID (32位十六进制)
             └─ 版本号

如果上下文在某个环节丢失，链路就会断裂，后续 Span 会各自成为新的根节点，交易定位随即失效。支付链路中最常见的断裂点是异步线程池、MQ 消费和第三方回调，这些位置必须显式做上下文透传。

三、采样策略：在成本与可观测性之间取舍

支付系统 QPS 高，若每条请求都完整采集，存储和传输成本会迅速失控。采样策略决定哪些 Trace 被记录。常见策略如下：

策略	原理	适用场景	风险
头部采样	在入口处按比例决定是否采样，标记随上下文传播	流量均匀、成本敏感	可能漏掉异常交易
尾部采样	先收集全部 Span，链路结束后按条件决定保留	需保留错误、慢请求	需缓冲，资源开销大
基于规则采样	按金额、渠道、错误码等业务属性决定	支付核心交易必采	规则维护成本高
自适应采样	根据实时流量动态调整采样率	流量波动大的系统	实现复杂

支付场景建议组合使用：核心大额交易与失败交易强制采样，普通查询类请求低比例头部采样，并对慢请求启用尾部采样兜底。

四、OpenTelemetry标准与实战场景

OpenTelemetry（OTel）已成为分布式追踪的事实标准，它统一了 API、SDK 与数据协议（OTLP），并提供与厂商无关的采集能力。其核心概念与前述模型一致：TracerProvider 负责创建 Tracer，Tracer 创建 Span，Span 通过 Context 传播。一个典型的 Java 埋点示例如下：

Span span = tracer.spanBuilder("pay.risk.check")
    .setAttribute("pay.amount", 19900)
    .setAttribute("pay.channel", "ALIPAY")
    .startSpan();
try (Scope scope = span.makeCurrent()) {
    riskClient.check(request);          // 业务调用
} catch (Exception e) {
    span.recordException(e);
    span.setStatus(StatusCode.ERROR);
    throw e;
} finally {
    span.end();
}

在交易定位场景中，运营拿到用户投诉后，先用订单号反查 TraceID，再用 TraceID 在追踪系统中打开完整链路，即可看到每个 Span 的耗时、状态与属性。例如发现“账务服务”Span 正常，但“渠道适配”Span 耗时 8 秒且状态为 ERROR，就能快速把问题定位到渠道侧，而不是盲目排查整个系统。

常见误区：只采集了 TraceID 却没有正确设置 parentSpanID，导致链路虽然能查到，但层级错乱、耗时无法归因；或在异步线程中直接新建 Span 而未继承上下文，使子调用变成孤立根节点。排查时应优先验证上下文传播是否完整。

掌握 Trace、Span、TraceID、SpanID、上下文传播、采样策略与 OpenTelemetry 标准，就具备了阅读和构建支付链路追踪数据的底层能力。后续的交易定位实战，都将建立在这套模型之上。