跟踪上下文

本文档简要介绍了上下文(即状态)和上下文传播(即将状态信息传递给子操作)。对于分布式跟踪,必须将轨迹 ID 和正在处理的跨度的 ID 传递给子操作。

子操作会创建一个 span 并设置以下字段:

  • Span ID:子操作的唯一标识符。如果多次执行相同的操作, 该操作的多个 span,每个 span 都有一个唯一标识符。
  • 轨迹 ID:发生此特定整体操作的端到端操作的唯一标识符。此字段的值由父级提供。
  • 父级 span ID:父级 span 的唯一标识符。此字段的值由父级提供。 对于根 span,此 ID 为 null

通过跟踪 ID、span ID 和父级 span ID 字段的值, 分布式跟踪系统正确地将 span 链接在一起以形成跟踪记录。 例如,Cloud Trace 将 span 存储在一个代码库中 用于标识哪些 span 构成跟踪记录的 ID 字段。

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

上下文传播协议

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

HTTP 请求

对于 HTTP 请求,上下文传播通常通过 HTTP 标头(例如 W3C 标准化traceparenttracestate 标头)来实现。支持轨迹上下文传播的 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 生成跟踪记录和指标

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

如果没有合适的插桩库, 您必须确保应用能够 将跟踪上下文映射到子操作。

后续步骤