跟踪上下文第 2 级

分布式跟踪是一种由跟踪工具实现的方法，用于跨多个软件组件跟踪、分析和调试一个 事务。通常，一个分布式跟踪 会穿越多个组件，因此要求它能够在所有参与 系统中被唯一标识。跟踪上下文传播会传递这种唯一标识。如今，跟踪上下文 传播由每个跟踪供应商分别实现。在多供应商环境中，这 会导致互操作性问题，例如：

• 不同跟踪供应商收集的跟踪无法关联，因为没有共享的 唯一标识符。
• 跨越不同跟踪供应商边界的跟踪无法传播，因为没有 一套统一约定的、会被转发的标识信息。
• 供应商特定的元数据可能会被中介丢弃。
• 云平台供应商、中介和服务提供商无法保证支持跟踪 上下文传播，因为没有可遵循的标准。

过去，这些问题并没有产生重大影响，因为大多数应用都由单一 跟踪供应商监控，并且停留在单一平台提供者的边界之内。如今，越来越多的应用 是高度分布式的，并利用多个中间件服务和 云平台。

现代应用的这种转变需要一个分布式跟踪上下文传播标准。

跟踪上下文规范定义了一种通用约定的格式，用于交换跟踪 上下文传播数据——称为跟踪上下文。跟踪上下文通过以下方式解决 上述问题：

• 为单个跟踪和请求提供唯一标识符，使多个 提供者的跟踪数据能够关联在一起。
• 提供一种约定机制，用于转发供应商特定的跟踪数据，并在 多个跟踪工具参与单个事务时避免跟踪中断。
• 提供一个中介、平台和硬件提供商都可以支持的行业标准。

用于传播跟踪数据的统一方法提高了对分布式 应用行为的可见性，有助于问题和性能分析。跟踪 上下文提供的互操作性是管理现代基于微服务的应用的前提条件。

Trace Context 规范的当前版本面向应用和服务的实现， 包括在浏览器中运行的 Web 应用。Web 浏览器或用户代理目前 不在目标实现范围内。

跟踪上下文被拆分为两个独立的传播字段，用以支持互操作性和 供应商特定的可扩展性：

• traceparent 用一种可移植、固定长度的格式描述传入请求在其跟踪图中的位置。 其设计侧重于快速解析。每个跟踪工具即便只依赖 tracestate 中的供应商特定信息，也 MUST 正确设置 traceparent
• tracestate 使用由一组名称/值对表示的供应商特定数据来扩展 traceparent。在 tracestate 中存储信息是可选的。

跟踪工具在与跟踪上下文交互时可以提供两个级别的一致行为：

• 至少它们 MUST 传播 traceparent 和 tracestate 标头，并保证跟踪不会中断。这种行为也称为 转发一个跟踪。
• 此外，它们 MAY 也可以选择通过修改 traceparent 标头以及 tracestate 标头中包含 其专有信息的相关部分来参与一个跟踪。这也称为参与一个跟踪。

跟踪工具可以针对它所监控组件的每个单独请求选择改变这种行为。

traceparent 请求标头以一种所有供应商都能理解的 通用格式表示跟踪系统中的传入请求。下面是一个 traceparent 标头示例。

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

tracestate 请求标头包含一个可能采用供应商特定格式表示的父项：

tracestate: congo=t61rcWkgMzE

例如，假设系统中的客户端和服务器使用不同的跟踪供应商：Congo 和 Rojo。一个 在 Congo 系统中被跟踪的客户端会向一个出站 HTTP 请求添加以下标头。

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
tracestate: congo=t61rcWkgMzE

注：在这种情况下，tracestate 值 t61rcWkgMzE 是 对父 ID（b7ad6b7169203331）进行 Base64 编码后的结果，尽管并不要求进行这种处理。

在 Rojo 跟踪系统中被跟踪的接收服务器会保留它收到的 tracestate，并在左侧添加一个新条目。

traceparent: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

你会注意到，Rojo 系统在其 tracestate 条目中复用了其 traceparent 的值。这意味着它是一个通用跟踪系统（没有传递 专有信息）。否则，tracestate 条目是不透明的，并且可以是 供应商特定的。

如果下一个接收服务器使用 Congo，它会保留来自 Rojo 的 tracestate，并在前一个条目的左侧 为父项添加一个新条目。

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01
tracestate: congo=ucfJifl5GOE,rojo=00f067aa0ba902b7

注：ucfJifl5GOE 是经过 Base64 编码的父 ID b9c7c989f97918e1。

注意，当 Congo 写入其 traceparent 条目时，它没有进行编码，这有助于 做关联的人保持一致性。然而，它的 tracestate 条目的值是经过编码的，并且 不同于 traceparent。这是可以的。

最后，你会看到 tracestate 完全按原样保留了 Rojo 的条目，只是被推到了 右侧。最左侧的位置让下一个服务器知道哪个跟踪系统对应于 traceparent。在这种情况下，因为 Congo 写入了 traceparent，所以它的 tracestate 条目应该位于最左侧。

traceparent HTTP 标头字段标识跟踪系统中的传入请求。它 有四个字段：

• version
• trace-id
• parent-id
• trace-flags

HEXDIGLC = DIGIT / "a" / "b" / "c" / "d" / "e" / "f" ; lowercase hex character
value           = version "-" version-format

version         = 2HEXDIGLC   ; this document assumes version 00. Version ff is forbidden

version-format   = trace-id "-" parent-id "-" trace-flags
trace-id         = 32HEXDIGLC  ; 16 bytes array identifier. All zeroes forbidden
parent-id        = 16HEXDIGLC  ; 8 bytes array identifier. All zeroes forbidden
trace-flags      = 2HEXDIGLC   ; 8 bit flags.

static final byte FLAG_SAMPLED = 1; // 00000001
static final byte FLAG_RANDOM = 2; // 00000010
...
boolean sampled = (traceFlags & FLAG_SAMPLED) == FLAG_SAMPLED;
boolean random = (traceFlags & FLAG_RANDOM) == FLAG_RANDOM;

Value = 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
base16(version) = 00
base16(trace-id) = 4bf92f3577b34da6a3ce929d0e0e4736
base16(parent-id) = 00f067aa0ba902b7
base16(trace-flags) = 01  // sampled

Value = 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00
base16(version) = 00
base16(trace-id) = 4bf92f3577b34da6a3ce929d0e0e4736
base16(parent-id) = 00f067aa0ba902b7
base16(trace-flags) = 00  // not sampled

tracestate HTTP 标头的主要目的是在不同分布式跟踪系统之间提供附加的 供应商特定跟踪标识信息，并且它是 traceparent 字段的配套标头。 它还传达请求在多个分布式跟踪图中的位置信息。

如果供应商未能解析 traceparent，则它 MUST NOT 尝试 解析 tracestate。注意，反过来并不成立：解析 tracestate 失败 MUST NOT 影响 traceparent 的解析。

tracestate HTTP 标头 MUST NOT 用于任何 不是由跟踪系统定义的属性。[BAGGAGE] MAY 可用于定义和传播此类应用级属性。

list  = list-member 0*31( OWS "," OWS list-member )
list-member = (key "=" value) / OWS

key = ( lcalpha / DIGIT ) 0*255 ( keychar )
keychar    = lcalpha / DIGIT / "_" / "-"/ "*" / "/" / "@"
lcalpha    = %x61-7A ; a-z

value    = 0*255(chr) nblk-chr
nblk-chr = %x21-2B / %x2D-3C / %x3E-7E
chr      = %x20 / nblk-chr

tracestate: rojo=00f067aa0ba902b7

tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

接收到没有 traceparent 标头的请求的供应商 SHOULD 为出站请求生成 traceparent 标头，从而有效地开始一个新的跟踪。 不这样做的一个可能原因可能是在性能敏感场景中，供应商决定 不采样某个请求。注意，对于大多数场景，即使不采样，也期望供应商生成该标头， 以便将采样决策传播到下游。

接收到 traceparent 请求标头的供应商 MUST 将其发送到 出站请求。它 MAY 在传递到 出站请求之前改变该标头的值。

如果 traceparent 字段的值在传播前未被更改， tracestate MUST NOT 也被修改。未修改的标头 传播通常在代理等透传服务中实现。这种行为也可以在当前不收集 分布式跟踪信息的服务中实现。

以下是允许的改变列表：

• 更新 parent-id：parent-id 字段的值可以设置为表示当前操作 ID 的新值。这是 最典型的改变，应被视为默认改变。
• 更新 sampled：sampled 字段的值反映调用方的记录行为：要么跟踪数据被丢弃，要么可能已 被带外记录。这可以通过双向切换该标志来表示。该 改变向下游供应商提供有关其父项信息被记录可能性的 信息。更新 sampled 标志时，parent-id 字段 MUST 被设置为新值。
• 重新开始跟踪：所有属性（trace-id、parent-id、 trace-flags）都会重新生成。该改变用于被定义为安全网络入口前门的服务， 并消除潜在的拒绝服务攻击面。供应商 SHOULD 在 traceparent 重新开始时清理 tracestate 集合。在少数情况下，重新开始后必须保留原始 tracestate 条目。这通常发生在跟踪流的某个点上 trace-id 被恢复回来时，例如，当它离开安全网络时。 然而，这 SHOULD 是一个明确的决定，而不是默认行为。
• 降级版本：本规范的此版本（00）定义了供应商在接收到更高版本的 traceparent 标头时的行为。在这种情况下，第一个改变是降级该 标头的版本。其他改变允许与此改变结合使用。

供应商 MUST NOT 对 traceparent 标头作出任何其他改变。

接收到 tracestate 请求标头的供应商 MUST 将其发送到 出站请求。它 MAY 在传递到 出站请求之前改变该标头的值。改变 tracestate 时，未修改键/值对的顺序 MUST 被保留。修改后的键 MUST 被移动到列表的 开头（左侧）。

以下是允许的改变：

• 添加新的键/值对。新的键/值对 SHOULD 被 添加到列表开头。添加键/值对 MUST NOT 导致 同一个键出现多次。
• 更新现有值。可以更新任何给定键的值。修改后的键 SHOULD 被移动到列表的开头（左侧）。
• 删除键/值对。任何键/值对 MAY 被 删除。供应商 SHOULD NOT 删除不是由它们生成的键。 删除未知键/值对会破坏其他系统中的关联。该改变 支持三种场景。第一种是代理可以出于隐私和安全顾虑阻止某些 tracestate 键。第二种场景是截断较长的 tracestate。最后，供应商 MAY 也可以丢弃 不是由它们生成的重复键。

traceparent 字段 MUST NOT 包含任何个人身份 信息。实现这一点的一种方式是使用不会暴露任何个人身份信息的随机数 生成器来随机生成所有 trace ID。任何用于生成 trace ID 的随机数生成器 MUST NOT 依赖任何可能具有个人身份属性的信息作为输入或种子 状态。

traceparent 字段的另一个隐私风险，是能够关联作为 单个事务一部分发出的请求。下游服务可能会跟踪并关联 单个事务中发出的两个或更多请求，并可能基于另一个请求中的 信息对某个请求调用方的身份作出推断。

注意，traceparent 字段的这些隐私顾虑是理论性的，而非 实际性的。某些发起或接收请求的服务 MAY 选择 重新开始一个 traceparent 字段，以完全消除这些风险。供应商 SHOULD 找到一种方法，尽量减少分布式跟踪 重新开始的次数，以促进跟踪供应商的互操作性。可以使用不同技术 代替重新开始。例如，服务可以定义上游和下游连接的信任边界，以及 任何请求可能带来的暴露级别。例如，供应商可能只针对来自或发往 外部服务的认证请求重新开始 traceparent。

服务还可以定义一种算法和审计机制，以验证 traceparent 字段中 传入或传出随机数的随机性。注意，该算法是 服务特定的，并非本规范的一部分。一个示例可能是时间算法，其中 将可逆哈希函数应用于当前时钟时间。接收方可以验证该时间 是否在约定边界内，这意味着该随机数是使用所要求的算法 生成的，并且实际上不包含任何个人身份信息。

tracestate 字段可以在任何键中包含任意不透明值。该标头的主要目的 是在不同分布式跟踪系统之间提供附加的供应商特定跟踪标识信息。

供应商 MUST NOT 在 tracestate 标头中包含任何个人身份信息。

对个人信息暴露极其敏感的供应商 MAY 实现 对未知键对应值的选择性移除。供应商 SHOULD NOT 改变 tracestate 字段，因为这会破坏允许多个 跟踪系统协作的目的。

当供应商在响应中包含 traceparent 和 tracestate 标头时，这些 值可能会无意中传递给跨源调用方。供应商应确保它们只在响应参与了该跟踪的系统时 包含这些响应标头。

如隐私一节所述，traceparent 和 tracestate 标头中的信息可能携带可被认为是敏感的信息。例如， traceparent 可能允许将一个请求与另一个请求发送的数据关联起来， 或者 tracestate 标头可能暗示调用方使用的监控软件版本。 这些信息可能被用于构建更大规模的攻击。

应用所有者应确保没有专有或机密信息存储在 tracestate 中，或者应确保发送到外部系统的请求中不存在 tracestate。

当在具有公共 API 的服务上启用分布式跟踪，并且天真地继续任何设置了 sampled 标志的跟踪时，恶意攻击者可能会用跟踪 开销压垮应用，伪造 trace-id 冲突使监控数据不可用，或者让你的 SaaS 跟踪供应商账单飙升。

跟踪供应商和平台应考虑这些情况，并确保设置制衡措施， 以防止恶意或编写不佳的调用方造成监控拒绝。

这种保护的一个示例可以是对认证请求和未认证请求采用不同的跟踪行为。 也可以实现各种数据记录速率限制器。

应用所有者需要确保测试所有会导致发送 traceparent 和 tracestate 标头的代码路径。例如，在单页浏览器 应用中，进行跨源请求很常见。如果这些代码路径之一导致 traceparent 和 tracestate 标头通过受 Access-Control-Allow-Headers [FETCH] 限制的跨源调用发送，则可能会失败。