トレースコンテキスト レベル 2

分散トレーシングは、複数のソフトウェアコンポーネントにまたがる トランザクションを追跡、分析、デバッグするために、トレーシングツールによって実装される方法論である。 通常、分散トレースは 複数のコンポーネントを通過するため、参加するすべての システムにわたって一意に識別可能である必要がある。トレースコンテキストの伝播は、この一意の識別を渡す。現在、トレースコンテキストの 伝播は、各トレーシングベンダーによって個別に実装されている。マルチベンダー環境では、これは 次のような相互運用性の問題を引き起こす:

• 共有された一意識別子がないため、異なるトレーシングベンダーによって収集されたトレースを 相関付けることができない。
• 一様に合意された転送対象の識別情報セットがないため、異なるトレーシングベンダー間の境界を越える トレースを伝播できない。
• ベンダー固有のメタデータが仲介者によって削除される可能性がある。
• 従うべき標準がないため、クラウドプラットフォームベンダー、仲介者、およびサービスプロバイダーは、トレース コンテキスト伝播のサポートを保証できない。

過去には、ほとんどのアプリケーションが単一のトレーシングベンダーによって監視され、 単一のプラットフォームプロバイダーの境界内に留まっていたため、これらの問題は大きな影響を持たなかった。現在では、 ますます多くのアプリケーションが高度に分散され、複数のミドルウェアサービスおよび クラウドプラットフォームを活用している。

現代のアプリケーションにおけるこの変化は、分散トレーシングコンテキスト伝播標準を必要としている。

トレースコンテキスト仕様は、トレース コンテキスト伝播データの交換のための、普遍的に合意された形式を定義する。このデータは trace context と呼ばれる。 トレースコンテキストは、上記で説明した問題を次のように解決する

• 個々のトレースおよびリクエストに一意識別子を提供し、複数 プロバイダーのトレースデータを相互にリンクできるようにする。
• ベンダー固有のトレースデータを転送し、複数のトレーシングツールが単一のトランザクションに参加する場合に トレースが分断されることを避けるための、合意されたメカニズムを提供する。
• 仲介者、プラットフォーム、およびハードウェアプロバイダーがサポートできる業界標準を提供する。

トレースデータを伝播するための統一されたアプローチは、分散 アプリケーションの挙動への可視性を高め、問題およびパフォーマンス分析を容易にする。トレース コンテキストが提供する相互運用性は、現代のマイクロサービスベースのアプリケーションを管理するための前提条件である。

Trace Context 仕様の現行バージョンは、ブラウザー内で実行される Web アプリケーションを含む、 アプリケーションおよびサービスによる実装を対象としている。Web ブラウザーまたはユーザーエージェントは、 現時点では対象実装の範囲外である。

トレースコンテキストは、相互運用性と ベンダー固有の拡張性をサポートする 2 つの個別の伝播フィールドに分割される:

• traceparent は、入力リクエストのトレースグラフ内での位置を、 移植可能な固定長形式で記述する。その設計は高速な解析に重点を置いている。すべてのトレーシングツールは、 tracestate 内のベンダー固有情報のみに依存する場合であっても、 traceparent を適切に設定しなければならない (MUST)
• tracestate は、名前/値ペアの セットで表されるベンダー固有データにより traceparent を拡張する。tracestate に情報を保存することは任意である。

トレーシングツールは、トレースコンテキストと相互作用する適合挙動として、2 つのレベルを提供できる:

• 最低限、traceparent および tracestate ヘッダーを伝播し、トレースが分断されないことを保証しなければならない (MUST)。この挙動は トレースの転送とも呼ばれる。
• 加えて、traceparent ヘッダーおよび 独自情報を含む tracestate ヘッダーの関連部分を変更することにより、トレースに参加することを 選択してもよい (MAY)。これは、トレースへの参加とも呼ばれる。

トレーシングツールは、監視対象のコンポーネントへの個々のリクエストごとに、この挙動を変更することを選択できる。

traceparent リクエストヘッダーは、トレーシングシステム内の入力リクエストを、 すべてのベンダーが理解する共通形式で表す。次に traceparent ヘッダーの例を示す。

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

tracestate リクエストヘッダーは、場合によりベンダー固有の形式で parent を含む:

tracestate: congo=t61rcWkgMzE

たとえば、あるシステムのクライアントとサーバーが、Congo と Rojo という異なるトレーシングベンダーを使用しているとする。Congo システムで トレースされるクライアントは、送信 HTTP リクエストに次のヘッダーを追加する。

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
tracestate: congo=t61rcWkgMzE

注記: この場合、tracestate 値 t61rcWkgMzE は parent ID (b7ad6b7169203331) を Base64 エンコードした結果である。ただし、そのような操作は 必須ではない。

Rojo トレーシングシステムでトレースされる受信サーバーは、受信した tracestate を 引き継ぎ、新しいエントリーを左側に追加する。

traceparent: 00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01
tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

Rojo システムが、その traceparent の値を tracestate 内の自分のエントリーに再利用していることに気付くはずである。これは、汎用トレーシングシステムであることを意味する (独自情報は渡されていない)。それ以外の場合、tracestate エントリーは 不透明であり、ベンダー固有であり得る。

次の受信サーバーが Congo を使用する場合、そのサーバーは Rojo からの tracestate を引き継ぎ、 前のエントリーの左側に parent 用の新しいエントリーを追加する。

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01
tracestate: congo=ucfJifl5GOE,rojo=00f067aa0ba902b7

注記: ucfJifl5GOE は、parent ID b9c7c989f97918e1 を Base64 エンコードしたものである。

Congo がその traceparent エントリーを書き込んだとき、それはエンコードされておらず、 これは相関付けを行う者にとって一貫性に役立つ。ただし、その tracestate エントリーの値はエンコードされ、 traceparent とは異なる。これは問題ない。

最後に、tracestate が Rojo のエントリーを元のまま保持し、右側に押し出されていることがわかる。 最左位置は、次のサーバーに対して、どのトレーシングシステムが traceparent に対応するかを知らせる。この場合、Congo が traceparent を書き込んだため、その tracestate エントリーは最左であるべきである。

traceparent HTTP ヘッダーフィールドは、トレーシングシステム内の入力リクエストを識別する。これは 4 つのフィールドを持つ:

• version
• trace-id
• parent-id
• trace-flags

HEXDIGLC = DIGIT / "a" / "b" / "c" / "d" / "e" / "f" ; lowercase hex character
value           = version "-" version-format

version         = 2HEXDIGLC   ; this document assumes version 00. Version ff is forbidden

version-format   = trace-id "-" parent-id "-" trace-flags
trace-id         = 32HEXDIGLC  ; 16 bytes array identifier. All zeroes forbidden
parent-id        = 16HEXDIGLC  ; 8 bytes array identifier. All zeroes forbidden
trace-flags      = 2HEXDIGLC   ; 8 bit flags.

static final byte FLAG_SAMPLED = 1; // 00000001
static final byte FLAG_RANDOM = 2; // 00000010
...
boolean sampled = (traceFlags & FLAG_SAMPLED) == FLAG_SAMPLED;
boolean random = (traceFlags & FLAG_RANDOM) == FLAG_RANDOM;

Value = 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
base16(version) = 00
base16(trace-id) = 4bf92f3577b34da6a3ce929d0e0e4736
base16(parent-id) = 00f067aa0ba902b7
base16(trace-flags) = 01  // sampled

Value = 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00
base16(version) = 00
base16(trace-id) = 4bf92f3577b34da6a3ce929d0e0e4736
base16(parent-id) = 00f067aa0ba902b7
base16(trace-flags) = 00  // not sampled

tracestate HTTP ヘッダーの主な目的は、異なる分散トレーシングシステム間で 追加のベンダー固有トレース識別情報を提供することであり、traceparent フィールドの 付随ヘッダーである。また、複数の分散トレーシンググラフ内におけるリクエストの位置に関する情報も伝達する。

ベンダーが traceparent の解析に失敗した場合、tracestate の解析を試みてはならない (MUST NOT)。 逆は真ではないことに注意する: tracestate の解析失敗は、 traceparent の解析に影響してはならない (MUST NOT)。

tracestate HTTP ヘッダーは、トレーシングシステムによって定義されていないプロパティに使用してはならない (MUST NOT)。 [BAGGAGE] は、 そのようなアプリケーションレベルのプロパティを定義および伝播するために使用してもよい (MAY)。

list  = list-member 0*31( OWS "," OWS list-member )
list-member = (key "=" value) / OWS

key = ( lcalpha / DIGIT ) 0*255 ( keychar )
keychar    = lcalpha / DIGIT / "_" / "-"/ "*" / "/" / "@"
lcalpha    = %x61-7A ; a-z

value    = 0*255(chr) nblk-chr
nblk-chr = %x21-2B / %x2D-3C / %x3E-7E
chr      = %x20 / nblk-chr

tracestate: rojo=00f067aa0ba902b7

tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

traceparent ヘッダーを持たないリクエストを受信したベンダーは、送信リクエスト用に traceparent ヘッダーを生成し、実質的に新しいトレースを開始すべきである (SHOULD)。 これを行わない理由として考えられるのは、ベンダーがリクエストをサンプリングしないと判断するパフォーマンスに敏感なシナリオである。 ほとんどのシナリオでは、サンプリングしない場合でも、下流にサンプリング判断を伝播するために、ベンダーはヘッダーを生成することが期待されることに注意する。

traceparent リクエストヘッダーを受信したベンダーは、それを 送信リクエストに送信しなければならない (MUST)。送信リクエストに渡す前に、このヘッダーの値を 変更してもよい (MAY)。

伝播前に traceparent フィールドの値が変更されなかった場合、 tracestate も変更してはならない (MUST NOT)。未変更のヘッダー 伝播は、通常、プロキシなどのパススルーサービスで実装される。この挙動は、現在 分散トレーシング情報を収集しないサービスでも実装される可能性がある。

許可される変更の一覧は次のとおりである:

• parent-id を更新する: parent-id フィールドの値は、現在の操作の ID を表す新しい値に設定できる。これは 最も典型的な変更であり、デフォルトとみなすべきである。
• sampled を更新する: sampled フィールドの値は、呼び出し元の記録挙動、すなわちトレースデータが削除されたか、 帯域外で記録された可能性があるかを反映する。これは、フラグを双方向に切り替えることで示すことができる。この 変更は、下流ベンダーに対して、その parent の情報が記録された可能性に関する情報を与える。 parent-id フィールドは、sampled フラグの更新とともに新しい値に 設定されなければならない (MUST)。
• トレースを再開始する: すべてのプロパティ (trace-id、parent-id、 trace-flags) が再生成される。この変更は、安全なネットワークへの フロントゲートとして定義されるサービスで使用され、潜在的なサービス拒否攻撃面を排除する。ベンダーは traceparent の再開始時に tracestate コレクションを クリーンアップすべきである (SHOULD)。 再開始後も元の tracestate エントリーを保持しなければならないまれな場合がある。 これは通常、トレースフローのある時点で trace-id が元に戻される場合に発生する。たとえば、 それが安全なネットワークを離れる場合である。 ただし、これは明示的な判断であるべきであり (SHOULD)、デフォルトの挙動であってはならない。
• バージョンをダウングレードする: この仕様のバージョン (00) は、より高いバージョンの traceparent ヘッダーを受信したベンダーについての挙動を 定義する。この場合、最初の変更はヘッダーの バージョンをダウングレードすることである。他の変更は、これと組み合わせて許可される。

ベンダーは、traceparent ヘッダーに対してその他の変更を行ってはならない (MUST NOT)。

tracestate リクエストヘッダーを受信したベンダーは、それを 送信リクエストに送信しなければならない (MUST)。送信リクエストに渡す前に、このヘッダーの値を 変更してもよい (MAY)。tracestate を変更する場合、変更されていないキー/値ペアの順序は 保持されなければならない (MUST)。変更されたキーは、リストの先頭 (左側) に移動されなければならない (MUST)。

許可される変更は次のとおりである:

• 新しいキー/値ペアを追加する。新しいキー/値ペアは リストの先頭に追加すべきである (SHOULD)。キー/値ペアを追加することで、 同じキーが複数回存在する結果となってはならない (MUST NOT)。
• 既存の値を更新する。任意のキーの値を更新できる。変更されたキーは、 リストの先頭 (左側) に移動すべきである (SHOULD)。
• キー/値ペアを削除する。任意のキー/値ペアを 削除してもよい (MAY)。ベンダーは、自身が生成していないキーを削除すべきではない (SHOULD NOT)。 未知のキー/値ペアの削除は、他のシステムにおける相関付けを壊す。この変更は 3 つのシナリオを可能にする。1 つ目は、プロキシがプライバシーおよびセキュリティ上の懸念から特定の tracestate キーをブロックできることである。2 つ目のシナリオは、長い tracestate の切り詰めである。最後に、ベンダーは 自身が生成していない重複キーを破棄してもよい (MAY)。

traceparent フィールドは、いかなる個人識別可能情報も 含んではならない (MUST NOT)。これを達成する 1 つの方法は、 個人識別可能情報を公開しない乱数 生成器を用いてすべての trace ID をランダムに生成することである。trace ID の生成に使用される任意の乱数生成器は、 入力または seed state として、潜在的に個人識別可能な情報に依存してはならない (MUST NOT)。

traceparent フィールドのもう 1 つのプライバシーリスクは、単一トランザクションの一部として行われるリクエストを 相関付ける能力である。下流サービスは、単一トランザクション内で行われる 2 つ以上のリクエストを追跡および相関付け、 あるリクエストから得られた情報に基づいて、別のリクエストの呼び出し元の身元について 推測する可能性がある。

これらの traceparent フィールドのプライバシー上の懸念は、実用的というより理論的なものであることに注意する。 リクエストを開始または受信する一部のサービスは、これらのリスクを完全に排除するために traceparent フィールドを再開始することを選択してもよい (MAY)。ベンダーは 分散トレース の再開始回数を最小化する方法を見つけ、トレーシングベンダーの相互運用性を促進すべきである (SHOULD)。再開始の代わりに、異なる技法を 使用してもよい。たとえば、サービスは上流および下流接続の信頼境界と、 任意のリクエストがもたらし得る露出レベルを定義してもよい。たとえば、ベンダーは 外部サービスから、または外部サービスへの認証リクエストについてのみ traceparent を再開始する可能性がある。

サービスは、traceparent フィールド内の入力または 出力ランダム数のランダム性を検証するためのアルゴリズムおよび監査メカニズムを定義してもよい。このアルゴリズムは サービス固有であり、この仕様の一部ではないことに注意する。1 つの例は、 可逆ハッシュ関数を現在の時計時刻に適用する時間的アルゴリズムである。受信者は、その時刻が 合意された境界内にあることを検証できる。これは、そのランダム数が必要なアルゴリズムで生成され、実際には 個人識別可能情報を含まないことを意味する。

tracestate フィールドは、いずれのキーにも任意の 不透明値を含んでもよい。このヘッダーの主な目的は、 異なる分散トレーシングシステム間で追加のベンダー固有トレース識別情報を提供することである。

ベンダーは、tracestate ヘッダーにいかなる個人識別可能情報も 含めてはならない (MUST NOT)。

個人情報の露出に極めて敏感なベンダーは、未知のキーに対応する値の 選択的削除を実装してもよい (MAY)。ベンダーは tracestate フィールドを変更すべきではない (SHOULD NOT)。それは複数のトレーシングシステムが協調できるようにする目的を損なうためである。

ベンダーがレスポンスに traceparent および tracestate ヘッダーを含める場合、これらの 値は意図せずクロスオリジン呼び出し元に渡される可能性がある。ベンダーは、トレースに参加したシステムに応答する場合にのみ、 これらのレスポンスヘッダーを含めるようにすべきである。

プライバシーの節で述べたように、traceparent および tracestate ヘッダー内の情報は、機微とみなされ得る情報を運ぶ可能性がある。たとえば、 traceparent は、あるリクエストを別のリクエストで送信されたデータと相関付けることを可能にする可能性があり、 また tracestate ヘッダーは、呼び出し元が使用する監視ソフトウェアのバージョンを示唆する可能性がある。 この情報は、より大きな攻撃を作成するために使用される可能性がある。

アプリケーション所有者は、独自情報または機密情報が tracestate に保存されていないことを保証するか、または外部システムへのリクエストに tracestate が存在しないことを保証すべきである。

公開 API を持つサービスで分散トレーシングが有効化されており、 sampled フラグが設定された任意のトレースを単純に継続する場合、悪意のある攻撃者は トレーシングオーバーヘッドでアプリケーションを圧倒したり、監視データを使用不能にする trace-id 衝突を偽造したり、SaaS トレーシングベンダーへの 請求額を増大させたりする可能性がある。

トレーシングベンダーおよびプラットフォームは、これらの状況を考慮し、悪意あるまたは不適切に作成された呼び出し元による 監視拒否から保護するための抑制と均衡が整っていることを確認すべきである。

そのような保護の例の 1 つは、認証済みリクエストと未認証リクエストで異なる トレーシング挙動をとることであり得る。データ記録のためのさまざまなレートリミッターも実装できる。

アプリケーション所有者は、 traceparent および tracestate ヘッダーの送信に至るすべてのコードパスをテストするようにしなければならない。たとえば、 シングルページブラウザーアプリケーションでは、クロスオリジンリクエストを行うことが一般的である。これらのコードパスの 1 つが、 Access-Control-Allow-Headers [FETCH] を使用して制限されるクロスオリジン呼び出しによって traceparent および tracestate ヘッダーが送信されることにつながる場合、 失敗する可能性がある。