このドキュメントでは、状態を指すコンテキストと、状態情報を子オペレーションに渡すことを表すコンテキスト伝播を指すコンテキストについて簡単に説明します。分散トレースの場合、トレース 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 進数 | Decimal |
以前の 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 サービスは、リクエスト処理の開始側または中間者として機能します。たとえば、次のサービスがリクエストの処理に関与することが知られています。
- Apigee
- App Engine
- Cloud Endpoints
- Cloud Functions
- Cloud Load Balancing
- Cloud Run
- Cloud Scheduler
- Cloud Tasks
- Pub/Sub
トレース コンテキストの開始と伝播のサポートは、特定の Google Cloud サービスによって異なります。Google Cloud サービスにコンテキストの伝播のサポートを追加をリクエストするには、Google Issue Tracker を使用します。
アプリケーションにおけるコンテキストの伝播
OpenTelemetry などの一部の計測ライブラリでは、トレースに必要なデータを含む context オブジェクトが自動的に伝播されます。これらのタイプのライブラリを使用すると、アプリケーションによって生成されたスパンが適切に構成されます。トレースをサポートする OpenTelemetry ライブラリの一覧については、言語 API と SDK をご覧ください。計測の例については、Go でトレースと指標を生成するをご覧ください。
オープンソースのライブラリに依存している場合は、コンテキストの伝播を使用できるかどうかと、構成が必要かどうかを判断します。
適切な計測ライブラリがない場合は、アプリケーションがトレース コンテキストを子オペレーションに伝播するようにする必要があります。
次のステップ
Trace のサンプリングについて学習する。
OpenTelemetry リソース: