Baggage API

状态: 稳定

概述

Baggage 是一组应用程序定义的属性，这些属性与分布式请求或工作流执行相关联（另请参阅 W3C Baggage 规范）。Baggage 可用于注释遥测数据，为指标、跟踪和日志添加上下文信息。

在 OpenTelemetry 中，Baggage 表示为一组描述用户定义的属性的名称/值对。Baggage 中的每个名称必须与恰好一个值相关联。这比 W3C Baggage 规范，§ 3.2.1.1 严格，后者允许为给定名称重复条目。

Baggage 名称可以是任何有效的、非空的 UTF-8 字符串。语言 API 不应限制用于 Baggage 名称的字符串。但是，用于在组件边界上传输 Baggage 条目的特定 Propagator 可能会强制执行自己的 Baggage 名称限制。例如，W3C Baggage 规范将 Baggage 密钥限制为满足 RFC7230，第 3.2.6 节中的 token 定义的字符串。为了最大程度的兼容性，强烈建议使用字母数字名称作为 Baggage 名称。

Baggage 值可以是任何有效的 UTF-8 字符串。语言 API 必须接受任何有效的 UTF-8 字符串作为 Set 中的 Baggage 值，并从 Get 返回相同的值。

语言 API 必须将 Baggage 名称和值都视为区分大小写的。另请参阅 W3C Baggage 原理。

示例

baggage.Set('a', 'B% 💼');
baggage.Set('A', 'c');
baggage.Get('a'); // returns "B% 💼"
baggage.Get('A'); // returns "c"

Baggage API 由以下组成：

  • Baggage 作为逻辑容器
  • 用于与 Context 中的 Baggage 交互的函数

此处描述的函数是通过拥有代表整个 Baggage 内容的 struct/对象来与 Baggage 交互的一种方法。根据语言习惯，语言 API 可能会通过直接与 Context 交互来实现这些函数。

Baggage API 在没有安装 SDK 的情况下必须是完全可用的。这是实现透明的跨进程 Baggage 传播所必需的。如果 Baggage 传播器安装到 API 中，无论是否有 SDK 安装，它都会正常工作。

Baggage 容器必须是不可变的，因此包含的 Context 也保持不可变。

操作

获取值

要访问由先前事件设置的名称/值对的值，Baggage API 必须提供一个函数，该函数以名称作为输入，并返回与给定名称相关联的值，如果给定名称不存在，则返回 null。

必需参数

Name 返回值的名称。

获取所有值

返回 Baggage 中的名称/值对。名称/值对的顺序无关紧要。根据语言特定情况，返回的值可以是不可变集合，也可以是 Baggage 中名称/值对的不可变集合的迭代器。

设置值

要记录名称/值对的值，Baggage API 必须提供一个函数，该函数以名称和值作为输入。返回一个包含新值的新 Baggage。根据语言习惯，语言 API 可能会使用 Builder 模式并公开一种从 Baggage 构建 Builder 的方法来实现这些函数。

必需参数

Name 要设置值的名称，类型为 string。

Value 要设置的值，类型为 string。

可选参数

Metadata 与名称-值对关联的可选元数据。这应该是字符串的不透明包装器，没有语义含义。保持不透明以允许将来的功能。

删除值

要删除名称/值对，Baggage API 必须提供一个函数，该函数以名称作为输入。返回一个不再包含所选名称的新 Baggage。根据语言习惯，语言 API 可能会使用 Builder 模式并公开一种从 Baggage 构建 Builder 的方法来实现这些函数。

必需参数

Name 要删除的名称。

上下文交互

本节定义了 Baggage API 中与 Context 交互的所有操作。

如果此 API 的实现不直接操作 Context，则必须提供以下功能与 Context 实例进行交互：

  • 从 Context 实例中提取 Baggage
  • 将 Baggage 插入 Context 实例

上述功能是必需的，因为 API 用户不应访问 Baggage API 实现使用的 Context Key。

如果语言支持隐式传播的 Context（请参阅 此处），API 还应提供以下功能：

  • 从隐式上下文中获取当前活动的 Baggage。这等同于获取隐式上下文，然后从上下文中提取 Baggage。
  • 将当前活动的 Baggage 设置到隐式上下文中。这等同于获取隐式上下文，然后将 Baggage 插入到上下文中。

以上所有功能仅操作于上下文 API，它们可以作为 Baggage 模块上的静态方法、Baggage 模块内某个类上的静态方法（该类可以命名为 BaggageUtilities）或 Baggage 类上的方法公开。如果可能，应在 API 中完全实现这些功能。

清除上下文中的 Baggage

为避免将任何名称/值对发送到不受信任的进程，Baggage API 必须提供一种从上下文中删除所有 Baggage 条目的方法。

此功能可以通过让用户将空的 Baggage 对象/结构体设置到上下文中来实现，或者通过提供一个接受 Context 作为输入并返回一个没有关联 Baggage 的新 Context 的 API 来实现。

传播

Baggage 可能出于各种原因在进程边界或任意边界（进程、$OTHER_BOUNDARY1、$OTHER_BOUNDARY2 等）之间传播。

API 层或扩展包必须包含以下 Propagator：

有关传播器的分发方式，请参阅 Propagators Distribution。

有关在将环境变量用作进程间通信的载体机制时如何处理传播，请参阅 Environment Variable Carriers。

注意：W3C Baggage 规范目前未为可选元数据分配语义含义。

在 extract 时，传播器应将所有元数据存储为每个条目的单个元数据实例。在 inject 时，传播器应按照 W3C 规范格式附加元数据。有关这些操作需要遵循的其他要求，请参阅 API Propagators Operation 部分。

冲突解决

如果添加了一个新的名称/值对，并且其名称与现有名称相同，则新对必须优先。该值将被添加的值替换（无论它是本地生成的还是从远程对等方接收的）。