4、Baggage 语义与传递：Baggage 的概念、与 Trace Context 的区别、Baggage 的序列化与反序列化规则

4.1 Baggage 的核心概念

Baggage 是 OpenTelemetry 中用于在服务间传递键值对元数据的机制。与 Trace Context 仅携带 Trace ID / Span ID / Sampled 标志不同，Baggage 允许开发者将业务上下文（如用户 ID、会话 ID、租户标识、AB 实验分组）附加到请求中，并随着分布式调用链自动传播。

Baggage 的典型使用场景包括：

• 租户隔离： 在 SaaS 系统中传递 tenant_id，下游服务据此进行数据隔离。
• AB 实验： 传递 experiment_group 标识，确保同一用户在整个请求链中命中相同的实验策略。
• 用户画像： 传递 user_role、membership_tier 等属性，用于差异化处理或日志增强。
• 请求溯源： 传递 source_channel、campaign_id 等营销属性，便于全链路归因分析。

4.2 Baggage 与 Trace Context 的区别

Trace Context 和 Baggage 虽然都通过 W3C 标准传播，但它们的职责、数据范围和传播规则有本质区别。下表从多个维度进行对比：

4.3 Baggage 的序列化与反序列化规则

W3C Baggage 规范定义了标准的序列化格式，用于在 HTTP 头中传递 Baggage 数据。其核心规则如下：

4.3.1 序列化规则（编码）

Baggage 数据被序列化为一个名为 baggage 的 HTTP 头，格式为逗号分隔的键值对列表：

baggage: key1=value1,key2=value2,key3=value3

详细规则：

• 键值对分隔： 使用逗号 , 分隔多个条目。
• 键值分隔： 使用等号 = 分隔键和值。
• URL 编码： 键和值中的特殊字符（如逗号、等号、空格、百分号）必须进行 Percent-Encoding（URL 编码）。
• 属性（Properties）： 每个条目可以附加可选的属性列表，使用分号 ; 分隔，属性格式为 key=value。
• 最大长度： 建议单个 Baggage 头不超过 8192 字节，条目数不超过 256 个。

带属性的完整示例：

baggage: user_id=12345,tenant_id=acme-corp;priority=high,experiment_group=test-a;ttl=3600

其中 tenant_id 条目附加了 priority=high 属性，experiment_group 条目附加了 ttl=3600 属性。

4.3.2 反序列化规则（解码）

反序列化时，接收方需要按照以下步骤解析 baggage 头：

1. 分割条目： 按逗号 , 分割整个头值，得到多个条目字符串。
2. 解析键值： 对每个条目，按第一个等号 = 分割为键和值。
3. URL 解码： 对键和值分别进行 Percent-Decoding。
4. 解析属性： 如果值部分包含分号 ;，则分号前为实际值，分号后为属性列表。属性列表按分号分割，每个属性再按等号分割为属性键和属性值。
5. 去重： 如果同一个键出现多次，以最后一次出现的值为准（或根据实现策略合并）。

4.3.3 序列化与反序列化流程

下图展示了 Baggage 在服务间传递时的序列化与反序列化完整流程：

4.4 Baggage 的传播范围与过滤

默认情况下，Baggage 会传播到所有下游服务。但在某些场景下，你可能希望限制传播范围，避免将内部上下文泄露到外部系统。OpenTelemetry 提供了两种控制机制：

• 传播器过滤： 在配置 Propagator 时，可以指定只传播特定的键前缀或正则匹配的条目。
• 上下文边界控制： 在调用外部服务前，通过 Baggage.builder().setParent(null) 创建空的 Baggage 上下文，从而阻断传播。

4.5 代码示例：手动操作 Baggage

以下示例展示了如何在 Java 中使用 OpenTelemetry API 手动设置和读取 Baggage：

// 设置 Baggage
Baggage baggage = Baggage.builder()
    .put("user_id", "12345")
    .put("tenant_id", "acme-corp", BaggageEntryMetadata.create("priority=high"))
    .build();
baggage.makeCurrent(); // 绑定到当前上下文

// 读取 Baggage
Baggage currentBaggage = Baggage.current();
String userId = currentBaggage.getEntryValue("user_id");
String tenantId = currentBaggage.getEntryValue("tenant_id");
BaggageEntryMetadata metadata = currentBaggage.getEntry("tenant_id").getMetadata();
// metadata.getValue() 返回 "priority=high"

// 在 HTTP 请求中自动传播（由 Propagator 处理）
// 无需手动设置 HTTP 头

在 Go 语言中的等价操作：

import "go.opentelemetry.io/otel/baggage"

// 设置 Baggage
member1, _ := baggage.NewMember("user_id", "12345")
member2, _ := baggage.NewMember("tenant_id", "acme-corp")
bag, _ := baggage.New(member1, member2)
ctx := baggage.ContextWithBaggage(context.Background(), bag)

// 读取 Baggage
bagFromCtx := baggage.FromContext(ctx)
userId := bagFromCtx.Value("user_id")
tenantId := bagFromCtx.Value("tenant_id")