本文档简要介绍了上下文,上下文指的是状态,以及 上下文传播是指将状态信息传递给 子操作。对于分布式跟踪,跟踪记录 ID 和 要处理的 span 必须传递给子操作。
子操作会创建一个 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 请求,上下文传播通常通过
traceparent
和 tracestate
标头等 HTTP 标头,
已经过 W3C 标准化。
支持跟踪记录上下文传播的 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 函数
- Cloud Load Balancing
- Cloud Run
- Cloud Scheduler
- Cloud Tasks
- Pub/Sub
对跟踪上下文启动和传播的支持是 具体取决于特定 Google Cloud 服务。 如需请求 Google Cloud 服务添加对上下文传播的支持,请执行以下操作: 使用 Google 问题跟踪器。
应用中的上下文传播
OpenTelemetry 等
自动传播包含必要数据的 context
对象
进行跟踪如果您使用这些类型的库,那么 span
并正确配置应用所生成的应用有关
有关支持跟踪的 OpenTelemetry 库,请参见
语言 API 和SDK。对于插桩
请参阅使用 Go 生成跟踪记录和指标。
如果您依赖于某个开源库,请确定 上下文传播是否可用以及是否需要配置。
如果没有合适的插桩库, 您必须确保应用能够 将跟踪上下文映射到子操作。
后续步骤
了解跟踪记录采样。
OpenTelemetry 资源: