トレース コンテキスト

トレース コンテキストとコンテキスト伝播により、分散アプリケーションはヘッダーまたはメタデータでサービス間でリクエスト ID を渡すことができます。Cloud Trace は、この共有コンテキストを使用して、個々のスパンを完全な分散トレースにリンクし、実行階層を再構築して、リクエストがサンプリングされるかどうかを評価します。

コンテキスト伝播の仕組み

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

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

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

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

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

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 ヘッダー

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 インストルメンテーション サンプルをご覧ください。

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

次のステップ