Baggage API (背包 API)

原文更新时间: 2021-02-04 翻译时间：2021-03-08

状态： 稳定， 功能冻结。

目录 - 概述 - 操作 - 获取值 - 获取全部值 - 设置值 - 删除值 - 与 Context 交互 - 清除 Context 中的 Baggage - 传播 - 冲突解决

概述

Baggage 用于注解遥测数据，给指标、追踪、日志增加上下文和信息。 它是一系列描述用户定义的属性的名字/值对。 Baggage 中的每个名称必须只关联一个值。

Baggage API 由以下组成:

  • Baggage

  • 用于 Baggage 与上下文交互的函数

这里定义的函数是指一种与拥有代表整个 Baggage 的结构体或对象进行交互的方式。取决于语言习惯，取决于语言习惯，语言 API 可能仅实现与 Context 交互的函数。

Baggage API 必须在没有安装 SDK 的情况下提供完整功能。这是为实现透明的跨进程 Baggage 传播所必须的。如果在 API 中安装了 Baggage 传播者，无论是否安装了 SDK，它都可以工作。

Baggage 的容器必须是不可变的, 这样包含的 Context 也是不可变的。

操作

获取值

Baggage API 必须提供一个函数用于要访问名称/值对中的值，该函数将上下文和名称作为参数输入，并返回一个值。返回的值与名称参数相关，如果提供的名称参数不存在，则返回空值。

必填参数: Name 要返回对应值的名称。

获取全部值

返回 Baggage 中的名称/值对。名称/值对的顺序必须不重要。取决于语言习惯，返回的值可以是一个不可变的集合，也可以是一个指向 Baggage 中的名称/值对集合的不可变迭代器。

设置 baggage

Baggage API 必须提供一个函数用于记录名称/值中的值，该函数接受一个名称和一个值作为输入参数。返回一个带有新值 Baggage 的 上下文。取决于语言习惯, 语言API可以使用构建者模式来从 Builder 构建出一个 Baggage。

必填参数:

Name 设置值的名称，字符串类型。

Value 要设置的值，字符串类型。

可选参数：

Metadata 与名称/值对相关联的元数据。这应当是对一个没有具体语义的字符串的不透明包装。以便于未来的功能拓展。

删除值

为了删除名称/值对，Baggage API 必须提供一个函数，接收一个名称作为输入参数。返回一个新的上下文，该上下文不再包含所选名称。取决于语言习惯, 语言 API 可以使用构建者模式来从 Builder 构建出一个 Baggage。

必填参数：

Name 要移除的名称。

与Context交互

此节定义所有与 Context 交互的有关 Baggage API 的操作

此 API 必须提供以下方法与 Context 实例交互。

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

上面列出的函数是必要的, 因为 API 用户应该不需要访问 Baggage API 实现相关的 Context 键

如果一种语言支持隐式传播 Context (参考此), 那么 API 应该提供以下方法:

  • 从隐式上下文中获取当前的 Baggage, 这等价于先获取隐式的上下文, 然后从上下文中提取 Baggage。
  • 设置当前的 Baggage 至隐式上下文中, 这等价于先获取隐式的上下文, 然后插入 Baggage 至上下文中。

清除Context中的Baggage

为了避免向不信任的进程发送任何的名称/值对，Baggage API 必须提供一种方式从 Context 中删除所有的 Baggage 条目。

这个函数可以通过用户设置一个空的 Baggage 对象/结构体至 Context 中来实现。 或者提供一个API, 它以 Context 作为输入参数, 返回一个不包含任何相关 Baggage 的新的 Context.

传播

Baggage 可能因为各种原因跨越进程边界或任意边界（进程，边界1, 边界2, 等等）进行传播。

API 层或扩展包必须包括以下 Propagator (传播者)。

参考 Propagators Distribution 了解传播者如何被分发。

注：W3C baggage 规范目前没有给可选项的元数据赋予语义。

当提取时，传播者应将所有元信息用一个元数据实例分配给各个条目。 当注入时，传播者应该根据W3C规范格式附加元数据。

注：

如果传播者无法解析传过来的 baggage ，提取 函数必须返回一个没有 Baggage 条目的上下文。

如果传过来的 baggage 存在，但不存在任何条目， 提取 函数必须返回一个没有 Baggage 条目的上下文。

冲突解决

如果添加新的名称/值对时已经存在同名，则新名称/值对的必须优先。值将被新添加的值替代（不论是本地生成还是从远处对等处接受）。