3. 上下文(Context)基础：SpanContext、Baggage、Propagator 的作用与数据结构

在分布式追踪与可观测性体系中，上下文（Context）是连接跨进程、跨服务调用链路的“隐形线”。对于 Collector 管道而言，上下文传播决定了配置同步事件能否在自助目录的多个处理阶段中被正确关联。本章聚焦三个核心概念：SpanContext、Baggage 和 Propagator，剖析它们的数据结构、职责边界以及在管道中的协作方式。

3.1 为什么需要上下文传播？

在自助目录的配置同步场景中，一条配置变更请求可能经历：

• 接收阶段：API Gateway 接收 YAML 配置
• 校验阶段：Schema 验证与冲突检测
• 同步阶段：写入分布式存储并触发通知
• 审计阶段：记录变更日志与指标

如果没有上下文传播，每个阶段产生的 Span 将彼此孤立，无法还原完整的请求链路；同时，关键的业务标签（如租户 ID、变更版本号）也无法跨阶段传递。这正是 SpanContext、Baggage 和 Propagator 需要协同解决的问题。

3.2 SpanContext：链路标识的基石

SpanContext 是 OpenTelemetry 中定义的最小上下文单元，它携带了唯一标识一条追踪链路的核心字段。其数据结构如下：

3.3 Baggage：业务语义的跨进程载体

Baggage 是 OpenTelemetry 提供的键值对容器，用于在服务间传递业务上下文。与 SpanContext 不同，Baggage 的内容由开发者自由定义，且会随请求传播到所有下游服务。

在自助目录的配置同步中，Baggage 的典型用途包括：

• 租户隔离：tenant_id=acme-corp
• 变更溯源：change_version=v2.1.0
• 优先级标记：sync_priority=high
• 审计标签：operator=jenkins-pipeline

3.4 Propagator：序列化与反序列化的桥梁

Propagator 负责将 SpanContext 和 Baggage 从进程内表示转换为可在网络协议中传输的格式（如 HTTP 头、gRPC 元数据），并在接收端还原。OpenTelemetry 定义了两种核心 Propagator：

• TraceContextPropagator：基于 W3C TraceContext 规范，处理 traceparent 和 tracestate 头
• BaggagePropagator：基于 W3C Baggage 规范，处理 baggage 头

在 Collector 管道中，Propagator 的典型工作流程如下：

1. 提取（Extract）：从入站请求的 HTTP 头中解析 traceparent 和 baggage，还原 SpanContext 与 Baggage
2. 注入（Inject）：在出站请求的 HTTP 头中写入 traceparent 和 baggage，确保下游服务能继续链路
3. 传递（Propagate）：在管道内部，通过 Context 对象将 SpanContext 和 Baggage 传递给下一个处理器

3.5 三者的协作关系

下图展示了 SpanContext、Baggage 和 Propagator 在 Collector 管道中的协作流程：

3.6 在 Collector 管道中的代码示例

以下示例展示了如何在 OpenTelemetry Collector 的处理器中访问和操作上下文：

// 伪代码：自定义 Collector 处理器中的上下文传播
func (p *SyncProcessor) ProcessTraces(ctx context.Context, td ptrace.Traces) (context.Context, ptrace.Traces) {
    // 1. 从 Context 中提取 SpanContext
    span := trace.SpanFromContext(ctx)
    sc := span.SpanContext()
    
    // 2. 从 Context 中提取 Baggage
    baggage := baggage.FromContext(ctx)
    tenantID := baggage.Get("tenant_id")
    changeVersion := baggage.Get("change_version")
    
    // 3. 在管道处理逻辑中使用上下文信息
    p.logger.Info("处理配置同步请求",
        "trace_id", sc.TraceID().String(),
        "tenant_id", tenantID,
        "change_version", changeVersion,
    )
    
    // 4. 如果需要向下游传递额外 Baggage，可以追加
    updatedBaggage, _ := baggage.SetMember(
        baggage,
        baggage.NewMember("processed_by", "sync-pipeline"),
    )
    ctx = baggage.ContextWithBaggage(ctx, updatedBaggage)
    
    return ctx, td
}

3.7 本章小结