Baggage 是什么
Baggage 是随请求在服务之间传播的键值对，属于分布式追踪上下文的扩展部分：调用方把租户、灰度标记、实验分组这类信息写进 baggage，下游服务无需改接口就能读到，可以据此给链路打标、筛选日志或决定采样策略。它随每次调用一路传递，内容必须小、稳定、不敏感。
基本信息
| 传播载体 | HTTP 使用 baggage 请求头，gRPC 走 metadata |
|---|---|
| 规范依据 | W3C Baggage 规范，与 trace 上下文配套使用 |
| 可见范围 | 完整链路上每个服务都可读取 |
| 常见取值 | 租户标识、灰度标记、实验分组、请求来源 |
传播格式与用法
传播格式与用法
# HTTP 头：多个键值对用逗号分隔
baggage: tenant=acme,gray=1,experiment=exp-42
# 读取后可作为 span 属性或日志字段，用于统一筛选
# OpenTelemetry 中通过 baggage API 读写，随上下文自动传播
# 注意：baggage 对每个下游都可见，不要放密码或令牌使用边界
| 方面 | 建议 | 原因 |
|---|---|---|
| 数据量 | 控制条目数量与值长度 | 每个下游都要解析，头过大放大每跳开销 |
| 内容性质 | 只放观测用途的标记 | 当配置通道用会引入隐式耦合 |
| 敏感信息 | 禁止放入 | 链路上任何服务都能读到 |
| 生命周期 | 随请求结束失效 | 不承担状态职责，不作为数据来源 |
典型使用场景
- 按租户维度过滤链路，定位单个客户的性能问题
- 给灰度流量打标，让灰度请求单独采样与观察
- 在日志里补充背景信息，让日志与链路互相印证
- 按实验分组对比链路指标，评估新逻辑的实际影响
baggage 与 trace 头分工不同：trace 头负责串联调用关系，baggage 负责携带业务上下文，跨服务调用时两者都需要正确透传。
baggage 值过长会抬高每个请求的头开销，条目数量与长度都要设上限，建议在网关侧做校验与截断。
调试时逐跳排查：先在入口确认 baggage 已写入，再确认下游是否读到，定位是哪一跳没有透传上下文。