トレース コンテキスト

このドキュメントでは、状態を指すコンテキストと、状態情報を子オペレーションに渡すことを表すコンテキスト伝播を指すコンテキストについて簡単に説明します。分散トレースの場合、トレース ID と処理中のスパンの ID を子オペレーションに渡す必要があります。

子オペレーションでは、スパンを作成し、次のフィールドを設定します。

  • Span ID: 子オペレーションの固有識別子。同じオペレーションが複数回実行された場合、そのオペレーションには複数のスパンがあり、それぞれに固有識別子があります。
  • Trace ID: この特定のオペレーション全体が行われたエンドツーエンドのオペレーションの固有識別子。このフィールドの値は親から提供されます。
  • Parent span ID: 親のスパンの固有識別子。このフィールドの値は親から提供されます。ルートスパンの場合、この ID は null です。

トレース ID、スパン ID、親スパン ID のフィールドの値によって、分散トレース システムでスパンを正しく一緒にリンクしてトレースを形成できます。たとえば、Cloud Trace はスパンをリポジトリに保存し、これらの ID フィールドを使用して、トレースを構成するスパンを特定します。

コンテキストには、分散トレースに役立つ他の状態情報が含まれる場合があります。たとえば、World Wide Web Consortium（W3C）標準には、親スパンがサンプリングされたかどうかについての情報が含まれます。

コンテキスト伝播用のプロトコル

以降のセクションでは、特定のリクエスト プロトコルがコンテキストを伝播する方法について説明します。

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 ヘッダーを引き続き使用できます。

次の表は、2 つのヘッダーの顕著な違いをまとめたものです。

属性 traceparent
ヘッダー		 X-Cloud-Trace-Context
ヘッダー
区切り文字 ハイフン (-) フォワード スラッシュ (/) とセミコロン (;)
スパン ID
表現		 16 進数 小数

以前の 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 は、128 ビットの番号を表す 32 文字の 16 進数値です。
  • SPAN_ID は、符号なしスパン ID の 64 ビット 10 進表現です。
  • OPTIONS は、0（親がサンプリングされていない）と 1（親がサンプリングされている）をサポートしています。

gRPC リクエスト

gRPC リクエストの場合、コンテキストの伝播は HTTP ヘッダーの上に実装される gRPC メタデータを使用して行われます。これは　HTTP ヘッダーの上に実装されます。gRPC アプリケーションは、traceparent ヘッダー、または grpc-trace-bin というメタデータ コンテキスト キーを使用する場合があります。

所有するコンポーネントの場合は、traceparent ヘッダーを使用することをおすすめします。

Google Cloud サービスのコンテキストの伝播

が含まれます。

Google Cloud サービスは、リクエスト処理の開始者または仲介者として機能する場合があります。たとえば、次のサービスがリクエストの処理に関与することが知られています。

トレース コンテキストの開始と伝播のサポートは、特定のサービスによって異なります。 Google Cloud Google Cloud サービスにコンテキストの伝播のサポートを追加をリクエストするには、Google Issue Tracker を使用します。

アプリケーションにおけるコンテキスト伝播

OpenTelemetry などの一部の計測ライブラリでは、トレースに必要なデータを含む context オブジェクトを伝播できます。トレースをサポートする OpenTelemetry ライブラリの一覧については、言語 API と SDK をご覧ください。

オープンソース ライブラリを使用している場合は、コンテキスト伝播が使用可能かどうか、構成が必要かどうかを判断します。たとえば、OpenTelemetry を使用して Go アプリを計測する場合は、SetTextMapPropagator を呼び出す必要があります。これにより、W3C traceparent 形式を使用するようにコンテキストが構成されます。例については、Go 計測サンプルをご覧ください。

適切な計測ライブラリがない場合は、アプリケーションがトレース コンテキストを子オペレーションに伝播するようにする必要があります。

次のステップ