OpenTelemetry のコンテキスト伝播と traceparent

traceparent、tracestate、Baggage の違いと、HTTP、gRPC、メッセージキューでトレースのつながりを確認する方法を解説します。

ベストプラクティス
システム間の接続とテレメトリーの流れを示すイメージ

チェックアウトのスパンは見えているのに、在庫サービスのスパンは別のトレース ID で記録されている。両方のサービスがスパンを正常に送信していても、この状況は起こります。まず在庫サービスが、チェックアウトから届いたコンテキストを取り出せているかを確かめます。

OpenTelemetry のコンテキスト伝播では、サービスの境界を越えてトレースの識別情報を渡します。受信側はスパンを開始する前にコンテキストを抽出します。次の呼び出しでは、送信側がその時点のスパンのコンテキストを注入します。この組み合わせで、後から親子関係をたどれます。

通信で受け渡す情報

SpanContext にはトレース ID、現在のスパン ID、トレースフラグ、トレースステートが入っています。抽出したリモートコンテキストから子スパンを作ると、トレース ID を引き継ぎ、新しいスパン ID が割り当てられます。親になるのは送信側のスパンです。開始時刻と終了時刻は個々のスパンに記録されます。抽出されたスパンコンテキストには、SDK がリモートの印を付けます。この印は SDK のコンテキスト内にあります。OpenTelemetry SpanContext API(英語)

Baggage は別のプロパゲーターが扱う任意のキーと値です。Baggage の値は自動ではスパン属性に入りません。たとえばリリースの配信グループで検索したい場合は、送信を許可した値をアプリケーションからスパン属性へ明示的にコピーします。

traceparent ヘッダーの読み方

W3C Trace Context Level 1 勧告(英語)のバージョン 00 は、version-trace-id-parent-id-trace-flags の順です。次の HTTP ヘッダーを受信したとします。

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
フィールド 受信側での意味
00 形式のバージョンです。ff は無効です。後続バージョンについては、Level 1 の規定に従い、解釈できる先頭部分の読み取りを試みます。
4bf92f3577b34da6a3ce929d0e0e4736 トレース ID です。小文字の16進数32文字で、すべてゼロの値は無効です。
00f067aa0ba902b7 送信側が伝播したスパン ID です。小文字の16進数16文字で、すべてゼロの値は無効です。
01 1バイトのフラグです。サンプリングの判断材料になるのは最下位ビット 0x01 です。実際に検索できるかどうかは、エクスポートや保存の設定にも左右されます。

有効な traceparent には、ベンダーの情報を順序付きで格納した任意の tracestate を添えられます。両端で互換性のあるプロパゲーターが使われているかを確認してください。OTEL_PROPAGATORS に対応する実装では、仕様上の既定値は tracecontext,baggage です。手動で SDK を組み込む場合は、プロパゲーターを明示的に設定します。OpenTelemetry Propagators API(英語) · SDK の環境変数(英語)

HTTP、gRPC、メッセージキューでの渡し方

HTTP。 クライアントの計装が送信ヘッダーにコンテキストを注入し、サーバーのミドルウェアがサーバースパンを作る前に抽出します。スパンを開始したら、返されたコンテキストを次の呼び出しへ渡します。古いコンテキストでリクエストを作ると、ヘッダーの形式が正しくても親を取り違えることがあります。

gRPC。 クライアントとサーバーの計装は、HTTP/2 ヘッダーで運ばれる RPC メタデータを使います。インターセプターやプロキシを経由する場合は、受信側のメタデータも確認します。gRPC のメタデータ(英語)

メッセージキュー。 プロデューサーは、たとえば Kafka レコードのヘッダーにメッセージ作成時のコンテキストを入れます。バッチを処理するコンシューマーは各メッセージからコンテキストを取り出し、処理スパンからそれぞれにリンクできます。親に指定できるスパンは一つだけです。OpenTelemetry のメッセージング規約では、既定の関連付けに Span Link を使います。単一メッセージの処理では、実装によって作成時のコンテキストを親にする場合があります。HTTP ハンドラーなどですでにスパンが有効なら、そのスパンを親として残し、メッセージの作成時コンテキストにリンクします。メッセージングのスパン規約(英語)

独自プロトコル。 メッセージのフィールドを、プロパゲーターが読み書きできるキャリアにします。注入・抽出を行い、受信側は抽出後のコンテキストでスパンを開始します。

伝播が途切れた境界を探す

テストリクエストを一つ流し、同期呼び出しごとに、送信した traceparent と次のサービスで抽出したコンテキストを照合します。受信側のサーバースパンは同じトレース ID を持ち、送信側のスパンを親としているはずです。キューでは親 ID とリンクを両方確認します。リンクを使うコンシューマーが別のトレース ID を持つことはあります。

想定外に ID が変わるときは、ヘッダーを取り除くゲートウェイ、計装されていないクライアント、コンテキストを引き継がずに始まった非同期処理を調べます。外部公開の入口では、信頼境界の方針に従って意図的に新しいトレースを作る場合もあります。ID が一致するのにスパンが見つからなければ、記録、サンプリング、エクスポートを確認し、バックエンドの期間と絞り込み条件も見直します。

Guance でトレースとログを照合する

DataKit の OTLP レシーバー(英語)にスパンを送ったら、テスト用トレースを検索して同期呼び出しの親 ID を確認します。非同期処理は、計装の出力で処理スパンのリンクを照合します。

同じリクエストのログを見るには、アプリケーションのログに有効なトレース ID を含め、APM とログの関連付けを設定します。ログにはトレース ID があるのに対応するスパンが見つからない場合は、その区間のサンプリングや送信状況を確認します。

Baggage を送る範囲を決める

外向きの呼び出しごとに、どのプロパゲーターが動くかを確認します。計装済みのクライアントから外部サービスを呼ぶと、Baggage が組織の外へ出る場合があります。送信するキーを絞り、認証情報や個人情報は含めず、受信した値は検証します。アクセス権限はサービスの認証とアプリケーションの認可で判断します。W3C Baggage(英語)

関連記事 · OpenTelemetryとは? · OpenTelemetry のサンプリング(英語)

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ