TraceState 处理

状态: 开发中

与 TraceContext 规范一致，本节使用 RFC5234 的增强型 Backus-Naur 记法 (ABNF)，包括该文档中的 DIGIT 规则。

当设置 OTel 生态系统中的 TraceState 值时，它们都必须包含在 ot 键下的单个条目中，其值为分号分隔的键值对列表，例如：

  • ot=p:8;r:62
  • ot=foo:bar;k1:13

TraceContext 规范支持多个“租户”，每个租户都可以使用自己的 tracestate 条目，通过在混合追踪环境中添加 tenant@ 前缀来表示租户特定的值。OpenTelemetry 识别此语法，但不指定对多租户 tracestate 的解释。该列表可正式定义为：

list        = list-member *( ";" list-member )
list-member = key ":" value

根据 TraceState 值部分的定义，完整列表长度不得超过 256 个字符，并且使用的键必须唯一。

Instrumentation 库和客户端不得使用此条目，而应使用自己的条目。

键

键是一个标识符，描述 OTel 的相关性。简单的例子是 p、ts 或 s1。

键可正式定义为：

key        = lcalpha *(lcalpha / DIGIT )
lcalpha    = %x61-7A ; a-z

OTel 相关性使用的特定键必须作为规范的一部分进行定义，因此禁止使用任何未在规范本身中定义的键。

值

值是一个不透明字符串。虽然没有允许的最大长度，但建议使用短值，因为 **整个** 键值对列表不得超过 256 个字符。

值可正式定义为：

value      = *(chr)
chr        = ucalpha / lcalpha / DIGIT / "." / "_" / "-"
ucalpha    = %x41-5A ; A-Z
lcalpha    = %x61-7A ; a-z

设置值

设置的值必须在 TraceState 的 ot 条目中进行更新或添加，以保留其他 OTel 相关性已有的值。例如，如果某个相关性 K 想设置 k1:13：

  • ot=p:8;r:62 将变为 ot=p:8;r:62;k1:13。
  • ot=p:8;k1:7;r:62 将变为 ot=p:8;r:62;k1:13。无需保留顺序。

如果设置值导致整个 ot 条目超过 256 个字符的限制，建议 SDK 中断操作并向用户发出错误信号，例如：

traceState, ok := SetTraceStateValue(traceState, value)
if ok {
  // Successfully set the specified value, traceState was updated.
} else {
  // traceState was not updated.
}

预定义的 OpenTelemetry 子键

以下值已由 OpenTelemetry 定义。

采样阈值 th

OpenTelemetry TraceState th 子键定义了一个采样阈值，它传达了有效的采样概率。th 子字段的有效值包括 1 到 14 个小写十六进制数字。

hexdigit = DIGIT ; a-f

要从 OpenTelemetry TraceState th 值中解码阈值，首先将值用尾随的零填充至 14 位。然后，将 14 位值解析为 56 位无符号十六进制数，得到一个拒绝阈值。

OpenTelemetry 定义了 56 位追踪随机值与 56 位拒绝阈值之间的一致采样。当随机值小于拒绝阈值时，span 不会被采样。

阈值 0 表示没有 span 被拒绝，对应 100% 采样。例如，以下 TraceState 值标识了一个 100% 采样的追踪：

tracestate: ot=th:0

要从拒绝阈值计算采样概率，定义一个常数 MaxAdjustedCount 等于 2^56，即 56 位值的不同数量。采样概率定义为：

Probability = (MaxAdjustedCount - Threshold) / MaxAdjustedCount

可以从概率计算阈值

Threshold = MaxAdjustedCount * (1 - Probability)

在采样中，“调整计数”是指由一个被采样的遥测项代表的有效项目数。span 的调整计数是其采样概率的倒数，可以通过阈值推导得出，如下所示。

AdjustedCount = MaxAdjustedCount / (MaxAdjustedCount - Threshold)

例如，这里有一个包含 OpenTelemetry 采样阈值的 W3C TraceState 值：

tracestate: ot=th:c

这对应于 25% 的采样概率，如下所示：

  • 十六进制值 c 被扩展为 c0000000000000 以表示 56 位
  • 拒绝阈值为 0xc0000000000000 / 0x100000000000000，即 75%
  • 采样概率为 25%。

显式随机值 rv

OpenTelemetry TraceState rv 子键定义了一个称为“显式随机值”的替代随机源。rv 的值必须是精确的 14 个小写十六进制数字。

显式随机值旨在替代从 TraceID 中提取随机性，因此它包含与 W3C Trace Context Level 2 推荐的 TraceID 相同的位数。

指定小写十六进制数字是为了实现采样阈值与 TraceID（在 traceparent 标头中表示）或显式随机值（在 tracestate 标头中表示）之间的直接字典序比较。

显式随机值旨在在 span context 中保持不变。不应从 OpenTelemetry TraceState 中删除显式随机值，也不应在与新的 TraceID 关联后修改它们，以使使用显式随机值的采样决策在不同信号之间保持一致。

例如，这里有一个包含 OpenTelemetry 显式随机值的 W3C TraceState 值：

tracestate: ot=rv:6e6d1a75832a2f

这对应于显式随机值，一个无符号整数值，为 0x6e6d1a75832a2f。该随机值旨在替代 TraceID 的最低有效 56 位。在此示例中，56 位分数（即 0x6e6d1a75832a2f / 0x100000000000000 = 43.1%）支持在 56.9% 到 100% 的概率范围内做出一致的正采样决策（即，拒绝阈值从 0x6e6d1a75832a2f 到 0），这与没有显式随机值的以 6e6d1a75832a2f 结尾的十六进制 TraceID 相同。