全链路追踪基础：OpenTelemetry 与 W3C Trace Context
在 API 网关延迟诊断场景中，仅靠单点指标无法定位跨服务瓶颈。全链路追踪（Distributed Tracing）通过记录请求在分布式系统中的完整传播路径，将延迟分解到每一次 RPC、数据库查询和消息队列操作。本章围绕 OpenTelemetry 规范、W3C Trace Context 协议、Trace/Span/Event 核心模型以及采样策略展开，为后续多集群追踪数据关联打下基础。
4.1 核心概念：Trace、Span 与 SpanEvent
全链路追踪的数据模型由三个基本元素构成：Trace（追踪）、Span（跨度）和 SpanEvent（事件）。
| 概念 | 定义 | 典型属性 |
|---|---|---|
| Trace | 代表一次完整请求的端到端路径，由一组具有相同 TraceID 的 Span 组成 | TraceID（全局唯一 16 字节）、开始时间、结束时间 |
| Span | Trace 中的一个工作单元，描述一次操作（如 HTTP 调用、数据库查询） | SpanID、ParentSpanID、操作名称、开始/结束时间戳、属性（Tags） |
| SpanEvent | Span 生命周期内的结构化日志，用于记录异常、关键变量或自定义标记 | 时间戳、事件名称、属性（Attributes） |
诊断要点：在 API 网关延迟分析中，重点关注 Span 的
duration 属性和 status.code（OK/ERROR）。SpanEvent 常用于记录网关层重试次数、熔断触发时刻或上游超时异常。
下图展示了一个包含 API 网关、服务 A 和服务 B 的 Trace 结构：
4.2 W3C Trace Context：跨服务传播标准
W3C Trace Context 定义了 HTTP 请求头中传递追踪上下文的规范，确保不同语言、不同 SDK 生成的 Trace 可以无缝关联。核心包含两个请求头：
- traceparent：携带 TraceID、SpanID 和 TraceFlags（采样标记）。格式：
00-{trace-id}-{parent-id}-{flags}。 - tracestate：携带供应商特定的扩展数据，用于传递采样优先级、租户信息等。
网关层关键动作：API 网关必须透传或生成
traceparent 头。如果上游未携带，网关应作为 Trace 的根节点生成新的 TraceID；如果已携带，则创建子 Span 并更新 parent-id。
W3C Trace Context 传播流程示意：
4.3 OpenTelemetry：统一观测标准
OpenTelemetry（OTel）是 CNCF 孵化的可观测性标准，提供与厂商无关的 API、SDK 和导出器。在 API 网关场景中，OTel 主要解决三个问题：
- 统一数据模型：使用 OTel 的 Span 和 SpanEvent 结构，避免供应商锁定。
- 自动插桩：通过 Agent 或 SDK 自动捕获 HTTP/gRPC/DB 调用，减少手动埋点。
- 多协议导出：支持 OTLP（原生协议）、Jaeger、Zipkin、Prometheus 等后端。
网关集成注意：API 网关通常运行在独立进程或 Sidecar 中，需确保 OTel SDK 版本与后端 Collector 兼容。推荐使用 OTel Collector 作为中间代理，统一处理采样、批处理和重试。
4.4 采样策略：在成本与精度间平衡
全量采样在高流量网关场景下会产生巨大的存储和计算开销。采样策略决定了哪些 Trace 被保留，直接影响延迟诊断的覆盖率和准确性。
| 采样策略 | 原理 | 适用场景 | 优缺点 |
|---|---|---|---|
| 固定比率采样 | 按固定概率（如 1%）随机保留 Trace | 低流量、监控大盘 | 实现简单；低概率时容易漏掉异常 |
| 头部采样 | 在请求入口处根据 TraceID 哈希决定是否采样 | 需要跨服务一致采样 | 保证完整 Trace；无法动态调整 |
| 尾部采样 | 在 Span 结束后根据延迟、错误码等条件决定是否保留 | 延迟诊断、错误分析 | 精准捕获慢请求；需要缓存所有 Span，内存开销大 |
| 概率+优先级采样 | 结合固定比率和动态优先级（如错误请求强制采样） | 生产环境通用 | 平衡成本与覆盖率；配置复杂 |
网关延迟诊断推荐：使用 尾部采样 + 优先级提升 策略。在 OTel Collector 中配置
tail_sampling 处理器，设置延迟阈值（如 p99 > 500ms）和错误状态码（5xx）为强制采样条件，其余请求按 5% 概率采样。
尾部采样决策流程：
4.5 网关层追踪配置示例（OpenTelemetry Collector）
以下是一个基于 OTel Collector 的尾部采样配置片段，适用于 API 网关延迟诊断场景：
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
processors:
tail_sampling:
decision_wait: 10s
num_traces: 100000
expected_new_traces_per_sec: 1000
policies:
# 策略1：延迟超过 500ms 的 Trace 强制采样
- name: latency-policy
type: latency
latency:
threshold_ms: 500
# 策略2：状态码为 5xx 的 Trace 强制采样
- name: error-policy
type: status_code
status_code:
status_codes:
- ERROR
# 策略3：其余 Trace 按 5% 概率采样
- name: probabilistic-policy
type: probabilistic
probabilistic:
sampling_percentage: 5
exporters:
jaeger:
endpoint: jaeger-collector:14250
tls:
insecure: true
service:
pipelines:
traces:
receivers: [otlp]
processors: [tail_sampling]
exporters: [jaeger]
调优建议：
decision_wait 控制尾部采样等待所有 Span 到达的时间，建议设为网关 p99 延迟的 2~3 倍。num_traces 是内存中缓存的最大 Trace 数，根据网关 QPS 和平均 Span 数估算，避免 OOM。
4.6 本章小结
- Trace/Span/Event 是全链路追踪的原子数据单元，API 网关作为入口节点，负责生成或透传 TraceID。
- W3C Trace Context 通过
traceparent和tracestate头实现跨服务上下文传递，是网关必须支持的协议。 - OpenTelemetry 提供统一的数据模型和导出机制，推荐使用 OTel Collector 作为采样和转发中间层。
- 采样策略 选择尾部采样 + 优先级提升，在保证异常和慢请求全量捕获的同时，控制存储成本。