本文档简要介绍了上下文(即状态)和上下文传播(即将状态信息传递给子操作)。对于分布式跟踪,必须将轨迹 ID 和正在处理的跨度的 ID 传递给子操作。
子操作会创建 span 并设置以下字段:
- Span ID:子操作的唯一标识符。如果多次执行同一操作,则该操作会有多个跨度,每个跨度都有一个唯一标识符。
- 轨迹 ID:发生此特定整体操作的端到端操作的唯一标识符。此字段的值由父级提供。
- 父级 span ID:父级 span 的唯一标识符。此字段的值由父级提供。对于根 span,此 ID 为
null
。
借助轨迹 ID、跨度 ID 和父级跨度 ID 字段的值,分布式跟踪系统可以正确地将跨度关联在一起,以形成轨迹。例如,Cloud Trace 会在代码库中存储 span,并使用这些 ID 字段来确定哪些 span 构成了跟踪记录。
上下文可能包含对分布式跟踪有用的一些其他状态信息。例如,万维网联盟 (W3C) 标准包含有关父级 span 是否已抽样的信息。
用于上下文传播的协议
以下部分介绍了特定请求协议如何传播上下文。
HTTP 请求
对于 HTTP 请求,上下文传播通常通过 HTTP 标头(例如 W3C 标准化的 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 服务可能会在请求处理中充当发起者或中介。例如,以下服务已知会参与处理请求:
- Apigee
- App Engine
- Cloud Endpoints
- Cloud Run functions
- Cloud Load Balancing
- Cloud Run
- Cloud Scheduler
- Cloud Tasks
- Pub/Sub
对轨迹上下文启动和传播的支持取决于特定 Google Cloud 服务。如需请求 Google Cloud 服务添加对上下文传播的支持,请使用 Google 问题跟踪器。
应用中的上下文传播
某些插桩库(例如 OpenTelemetry)会自动传播包含跟踪所需数据的 context
对象。如果您使用这些类型的库,则应用生成的跨度会正确配置。如需查看支持跟踪的 OpenTelemetry 库的列表,请参阅语言 API 和 SDK。如需查看插桩示例,请参阅使用 Go 生成跟踪记录和指标。
如果您依赖于开源库,请确定上下文传播是否可用以及是否需要进行配置。
如果没有合适的插桩库,您必须确保应用将轨迹上下文传播到子操作。
后续步骤
了解轨迹抽样。
OpenTelemetry 资源: