トレース コンテキスト

トレース コンテキストとコンテキスト伝播は、オペレーションとサービス間で メタデータを渡すために使用されるメカニズムです。これにより、Cloud Trace は 個々のスパンをリンクして、完全なエンドツーエンドの分散トレースを作成できます。

アプリケーションがリクエストを処理してダウンストリーム サービスを呼び出すと、リクエスト ヘッダーまたはメタデータを使用して、トレース ID、親スパン ID、サンプリング ステータスなどの識別子が渡されます。子オペレーションでは、このコンテキストを使用して、新しいスパンに次のフィールドを設定します。

  • スパン ID: 子オペレーションの固有識別子。オペレーションが複数回実行されると、呼び出しごとに異なるスパン ID を持つスパンが生成されます。
  • トレース ID: 親から提供される、エンドツーエンドのリクエスト全体の固有識別子。
  • 親スパン ID: 呼び出し元の親スパンの固有識別子。ルートスパンの場合、このフィールドは null です。

Cloud Trace は、これらの共有識別子を使用して実行階層を再構築し、参加しているすべてのサービス間のレイテンシを測定します。コンテキスト には、リクエストが サンプリングされたかどうかなど、追加の状態情報を含めることもできます。

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

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

HTTP リクエスト

HTTP リクエストの場合、コンテキストの伝播は通常、 HTTP ヘッダーを通じて行われます。これらは traceparent および tracestate ヘッダーなどの HTTP ヘッダーを通じて行われます。これらは W3C によって 標準化されています。traceparent ヘッダーには、リクエストを一意に識別するための識別子が含まれています。一方、tracestate ヘッダーは省略可能で、ベンダー固有のメタデータが含まれています。

traceparent ヘッダーには次の形式があります。

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

traceparent ヘッダーのフィールドは次のように定義されます。

  • VERSION はヘッダー バージョンです。必ず 00 を指定します。
  • TRACE_ID は、128 ビットの番号を表す 32 文字の 16 進数値です。
  • PARENT_SPAN_ID は、親スパンを識別する 16 文字の 16 進数値です。
  • TRACE_FLAGS は、親のサンプリング決定を識別する 2 文字の 16 進数値です。親がスパンをサンプリングした場合、値は 01 になります。

Google Cloud トレース コンテキストの伝播をサポートする サービスは通常、 traceparent と 以前の X-Cloud-Trace-Context ヘッダーの両方をサポートします。

可能な場合は、アプリケーションで traceparent ヘッダー を使用してください。アプリケーションが X-Cloud-Trace-Context ヘッダーのみをサポートしている場合は、traceparent ヘッダーをサポートして優先するようにアプリケーションを更新することをおすすめします。アプリケーションは、フォールバック ソリューションとして X-Cloud-Trace-Context ヘッダーを引き続き使用できます。

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

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

以前の X-Cloud-Trace-Context ヘッダー

が使用する X-Cloud-Trace-Context ヘッダーは、 Google Cloud 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 計測のサンプルをご覧ください。

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

次のステップ