跟踪上下文

本文档简要介绍了“上下文”（指状态）和“上下文传播”（指将状态信息传递给子操作）。对于分布式跟踪，必须将跟踪记录 ID 和所处理的 span 的 ID 传递给子操作。

子操作会创建 span 并设置以下字段：

  • Span ID：子操作的唯一标识符。如果多次执行同一操作，则该操作有多个 span，每个 span 都具有唯一标识符。
  • 跟踪记录 ID：执行此特定整体操作的端到端操作的唯一标识符。此字段的值由父级提供。
  • 父级 span ID：父级 span 的唯一标识符。此字段的值由父级提供。 对于根 span，此 ID 为 null。

跟踪记录 ID、span ID 和父 span ID 字段的值可让分布式跟踪系统正确地将 span 链接在一起以形成跟踪记录。例如，Cloud Trace 将 span 存储在代码库中，并使用这些 ID 字段来识别构成跟踪记录的 span。

上下文可能包含对分布式跟踪有用的其他状态信息。例如，万维网联盟 (W3C) 标准包含有关父级 span 是否进行了抽样的信息。

上下文传播协议

以下部分介绍特定请求协议如何传播上下文。

HTTP 请求

对于 HTTP 请求，上下文传播通常通过 W3C 已标准化的 HTTP 标头（例如 traceparent 和 tracestate 标头）完成。支持轨迹上下文传播的 Google Cloud 服务通常同时支持 traceparent 和旧版 X-Cloud-Trace-Context 标头。

我们建议您尽可能在应用中使用 traceparent 标头。您的应用可能需要使用旧版 X-Cloud-Trace-Context 标头，或者可能需要支持接收不同格式的跟踪上下文。

如果您的应用仅支持 X-Cloud-Trace-Context 标头，我们建议您更新应用，以支持 traceparent 标头并确定其优先级。您的应用可以继续使用 X-Cloud-Trace-Context 标头作为回退解决方案。

下表总结了这两个头文件之间的一些显著差异：

属性 traceparent
标题		 X-Cloud-Trace-Context
标题
分隔符 连字符 (-) 正斜杠 (/) 和分号 (;)
Span ID
表示法		 十六进制 十进制

旧版 X-Cloud-Trace-Context 标头

Google Cloud 使用的 X-Cloud-Trace-Context 标头早于 W3C 规范。为了实现向后兼容性，某些 Google Cloud 服务会继续接受、生成和传播 X-Cloud-Trace-Context 标头。不过，这些系统可能也支持 traceparent 头文件。

X-Cloud-Trace-Context 标头采用以下格式：

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS

标头字段的定义如下：

  • TRACE_ID 是一个 32 个字符的十六进制值，表示一个 128 位的数字。
  • SPAN_ID 是无符号 span ID 的 64 位十进制表示法。
  • OPTIONS 支持 0（父级未采样）和 1（父级未采样）。

gRPC 请求

对于 gRPC 请求，使用 gRPC 元数据完成上下文传播，该元数据在 HTTP 标头之上实现。gRPC 应用可以使用 traceparent 标头或名为 grpc-trace-bin 的元数据上下文键。

对于您拥有的组件，我们建议您使用 traceparent 标头。

Google Cloud 服务的上下文传播

在请求处理过程中，Google Cloud 服务可充当发起方或中间方。例如，已知以下服务会参与处理请求：

对跟踪上下文的启动和传播的支持取决于特定的 Google Cloud 服务。如需请求 Google Cloud 服务添加对上下文传播的支持，请使用 Google 问题跟踪器。

应用中的上下文传播

某些插桩库（如 OpenTelemetry）会自动传播包含跟踪所需数据的 context 对象。如果您使用这些类型的库，请正确配置应用生成的 span。如需查看支持跟踪的 OpenTelemetry 库的列表，请参阅语言 API 和 SDK。如需查看插桩示例，请参阅使用 Go 生成跟踪记录和指标。

如果您依赖于开源库，请确定上下文传播是否可用以及是否需要配置。

如果没有合适的插桩库，您必须确保应用将跟踪上下文传播到子操作。

后续步骤