跟踪上下文

借助跟踪记录上下文和上下文传播，分布式应用可以在标头或元数据中跨服务传递请求标识符。Cloud Trace 使用此共享上下文将各个 span 关联到完整的分布式跟踪记录中，重建执行层次结构，并评估是否对请求进行了抽样。

上下文传播的运作方式

当应用处理请求并调用下游服务时，它会使用请求标头或元数据传递标识符（例如跟踪记录 ID、父 span ID 和抽样状态）。子操作使用此上下文来填充新 span 中的以下字段：

  • Span ID：子操作的唯一标识符。如果某项操作执行多次，则每次调用都会生成一个具有不同 span ID 的 span。
  • 跟踪 ID：由父级提供的整个端到端请求的唯一标识符。
  • 父 span ID：调用父 span 的唯一标识符。对于根 span，此字段为 null。

借助这些共享标识符，Trace 可以重建执行层次结构并衡量所有参与服务之间的延迟时间。情境还可以包含其他状态信息，例如请求是否经过抽样。

上下文传播协议

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

HTTP 请求

对于 HTTP 请求，上下文传播通常通过 HTTP 标头（例如 traceparent 和 tracestate 标头）完成，这些标头已由 W3C 标准化。traceparent 标头包含用于唯一标识请求的标识符。相比之下，tracestate 标头是可选的，其中包含特定于供应商的元数据。

traceparent 标头采用以下格式：

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

traceparent 标头的字段定义如下：

  • VERSION 是标头版本。必须为 00。
  • TRACE_ID 是一个 32 个字符的十六进制值，表示一个 128 位的数字。
  • PARENT_SPAN_ID 是一个 16 字符的十六进制值，用于标识父 span。
  • TRACE_FLAGS 是一个 2 字符的十六进制值，用于标识父级的抽样决策。如果父级对 span 进行了采样，则值为 01。

支持跟踪记录上下文传播的Google Cloud 服务通常同时支持 traceparent 和旧版 X-Cloud-Trace-Context 标头。

尽可能在应用中使用 traceparent 标头。如果应用仅支持 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 对象。如需查看支持跟踪的 OpenTelemetry 库的列表，请参阅语言 API 和 SDK。

如果您依赖于某个开源库，请确定该库是否支持上下文传播，以及是否需要进行配置。例如，如果您使用 OpenTelemetry 对 Go 应用进行插桩，则应用应调用 SetTextMapPropagator，该函数会将上下文配置为使用 W3C traceparent 格式。如需查看示例，请参阅 Go 插桩示例。

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

后续步骤