可观测性与稳定性 / 系统课时
使用 Baggage 传递业务上下文
使用 Baggage 传递业务上下文
Baggage 适合把少量、需要跨服务继续使用的业务上下文随请求一起传播,例如租户标识或实验分组。本篇会完成一次 W3C Baggage 注入与提取,并建立敏感信息、可信边界和传播体积的控制规则。
学习目标
- 区分 Baggage、Span Context 与 Span Attributes 的职责
- 使用 OpenTelemetry JavaScript API 注入、提取并读取 Baggage
- 设计可控的业务字段白名单,避免敏感信息和传播膨胀
先确定 Baggage 的职责
Baggage 是跟随 OpenTelemetry Context 传播的键值集合。它解决的是“下游还需要知道这项上下文”的问题,而不是“把所有业务字段都记录到 Trace”。Baggage 中的值不会自动变成 Span Attributes;如果确实要查询它,仍应在目标服务显式读取并写入 Span。
适合传播的通常是短小、稳定、对多个下游有解释价值的字段,例如 tenant.id、checkout.flow 或实验桶。订单详情、大段 JSON、访问令牌、Cookie、身份证号等内容不应进入 Baggage。
看懂一次跨服务传播
发送端先把 Baggage 放入当前 Context,再由 Propagator 写入 HTTP 头、RPC metadata 或消息属性等 carrier。接收端从 carrier 提取出新的 Context,之后才能读取其中的 Baggage。这个过程与 Trace Context 并行,但两者承载的信息不同。

在真实应用里,通常同时启用 W3C Trace Context 与 W3C Baggage Propagator。这样 traceparent 负责追踪关系,baggage 负责业务上下文;不要把业务字段塞进 traceparent,也不要用 Baggage 替代 Trace 的父子关系。
完成一次注入与提取
下面示例只模拟 carrier 往返,不依赖 HTTP 框架。运行前需要项目已安装 @opentelemetry/api 与 @opentelemetry/core。示例同时注册 Trace Context 与 Baggage Propagator,但由于没有创建 Span,最终 carrier 只会出现 baggage。
import { ROOT_CONTEXT, propagation } from '@opentelemetry/api';
import {
CompositePropagator,
W3CBaggagePropagator,
W3CTraceContextPropagator,
} from '@opentelemetry/core';
propagation.setGlobalPropagator(
new CompositePropagator({
propagators: [
new W3CTraceContextPropagator(),
new W3CBaggagePropagator(),
],
}),
);
const baggage = propagation.createBaggage({
'tenant.id': { value: 'tenant-42' },
'checkout.flow': { value: 'express' },
});
// Context 与 Baggage 都是不可变语义:setBaggage 会返回新 Context。
const outgoingContext = propagation.setBaggage(ROOT_CONTEXT, baggage);
const carrier: Record<string, string> = {};
propagation.inject(outgoingContext, carrier);
console.log(`header=${carrier.baggage}`);
const incomingContext = propagation.extract(ROOT_CONTEXT, carrier);
const incomingBaggage = propagation.getBaggage(incomingContext);
console.log(`tenant=${incomingBaggage?.getEntry('tenant.id')?.value}`);
console.log(`flow=${incomingBaggage?.getEntry('checkout.flow')?.value}`);预期输出
header=tenant.id=tenant-42,checkout.flow=express
tenant=tenant-42
flow=express实际服务中,框架或自动插桩可能替你完成 inject 与 extract,但业务代码仍应明确决定“哪些字段可以进入 Baggage”。读取后若需要在追踪后台筛选,可把允许的值显式写成 Span Attribute,例如把 tenant.id 映射到内部约定的低风险属性名。
控制敏感信息与传播开销
最稳妥的做法是把 Baggage 当作一个严格白名单,而不是任意透传字典。字段应数量少、值短、生命周期明确,并能说明为什么每个下游都需要它;不要把协议允许的最大体积当作业务预算。
跨越可信边界时应重新审查 Baggage。调用第三方 API 前,可以构造不含内部业务字段的新 Context,或只保留经过批准的键;接收公网请求时,也应把外部 Baggage 视为不可信输入,必要时丢弃、重写或校验格式。
什么时候不要用 Baggage
Baggage 不适合传递认证状态、权限判定、会话凭据、完整业务对象或大文本。授权应依赖经过验证的身份机制,业务数据应走正式请求字段、消息体或数据存储。把 Baggage 保持为“小、少、非敏感、可丢弃”的上下文,才能同时保住可观测性和传播边界。