traceparent デコーダー — W3C Trace Context

traceparent ヘッダーとは？

# The header as it travels on the wire
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate:  rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

# Read the four fields apart
#   version     00
#   trace-id    4bf92f3577b34da6a3ce929d0e0e4736   (16 bytes, whole request)
#   parent-id   00f067aa0ba902b7                   (8 bytes, calling span)
#   trace-flags 01                                 (bit 0 set = sampled)

# Send one yourself
$ curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
       https://example.com/api

主な機能

traceparent の解析例

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

version 00 · trace-id 4bf92f3577b34da6a3ce929d0e0e4736 · parent-id 00f067aa0ba902b7 · trace-flags 01 (sampled)

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00

有効なヘッダー · sampled ビットは0

00-00000000000000000000000000000000-00f067aa0ba902b7-01

無効 — trace-id がオールゼロ

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

x-datadog-trace-id 11803532876627986230 · _dd.p.tid 4bf92f3577b34da6

traceparent デコーダーの使い方

1. 1

   traceparent ヘッダーを貼り付ける

   生のヘッダー値をそのまま入れてください。例：00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01。解析は入力に合わせて進むので、押すボタンはありません。

2. 2

   4つのフィールドを分けて読む

   version・trace-id・parent-id・trace-flags がそれぞれ独立した行に分かれ、行ごとにコピーボタンが付きます。32文字を手で選択しなくても、trace ID だけをクエリに持ち出せます。

3. 3

   フラグを1ビットずつ確認する

   trace-flags のバイトはマスク付きで8ビットすべてに展開されます。sampled と Level 2 の random-trace-id フラグが、2文字の値の中に埋もれず個別に見えます。

4. 4

   使っているバックエンドの形式へ変換する

   Datadog・AWS X-Ray・B3 の2形式が下に生成されます。Datadog が期待する下位64ビットの10進 trace ID と、それに伴う上位64ビットのタグも含まれます。

5. 5

   tracestate を足して結果を共有する

   tracestate ヘッダーを貼るとメンバーが1件ずつ検証付きで一覧化され、32メンバーの上限に対する件数も出ます。あとはリンクをコピーで、今の状態をそのまま URL にしてチケットに貼れます。

traceparent でよくある間違い

if (traceFlags === 0x01) { record(); }

if (traceFlags & 0x01) { record(); }

x-datadog-trace-id: 100985939111033328018442752961257817910

x-datadog-trace-id: 11803532876627986230
x-datadog-tags: _dd.p.tid=4bf92f3577b34da6

if (version !== '00') throw new Error('bad traceparent');

if (version !== '00' && header.length >= 55) { /* parse the known prefix */ }

traceparent: 00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

traceparent デコーダーでできること

トレースに span がない理由を突き止める

受け取ったヘッダーを貼って sampled ビットを読みます。落ちていれば、そのトレースはもともと記録される予定がなく、答えは自分の計装ではなく呼び出し元にあります。この切り分けだけで、自分のサンプラー設定を洗う時間が大きく浮きます。

バックエンドで見つからないトレースを探す

アプリのログからコピーした trace ID が Datadog で何も返さないとき、たいていは形式が原因です。ここで変換すれば、API が期待する下位64ビットの10進識別子と、それに添える必要のある上位64ビットのタグが分かります。

ゲートウェイが注入するヘッダーを検証する

プロキシやサービスメッシュは受信時にトレースコンテキストを生成します。実際に届いた値を貼って、長さ・小文字の16進・非ゼロの識別子を確かめてから、下流のせいだと判断してください。

本番のトレースを手作業で再現する

実リクエストのヘッダーを取り、ステージングのエンドポイントに投げ直して同じトレースを追います。リクエストは curl コマンドビルダー で組み立て、ヘッダーをそのまま貼り込めます。

チームにトレースコンテキストを説明する

このページのフィールド解剖表と trace-flags 表は、そのまま指し示せる静的な参照資料です。プリセットのチップを使えば、誰かがサービスを壊さなくても各異常系を実演できます。

W3C Trace Context バリデーターの仕組み

4フィールドの文法

version "-" trace-id "-" parent-id "-" trace-flags で、すべて小文字の16進です。version は2桁、trace-id は32桁、parent-id は16桁、trace-flags は2桁——16進52桁とハイフン3個で、version 00 ではちょうど55文字になります。値が正しく見えても大文字の16進はヘッダーを無効にします。またオールゼロの trace-id と parent-id は、空ではなく明示的に無効です。

trace-flags はビットフィールド

ビット0（マスク 0x01）は sampled で、立っていれば呼び出し元がトレースデータを記録した可能性があります。ビット1（マスク 0x02）は Level 2 で導入された random-trace-id で、立っている場合は trace-id の少なくとも右端7バイトが一様分布の乱数で選ばれている必要があり、下流のシステムはそれを使ってサンプリングやシャーディングができます。ビット2から7は予約で、受信時は無視し、送信時はクリアしなければなりません。予約ビットが存在しうる以上、このフィールドはビット AND で判定する必要があります。0x01 との等値比較は、予約ビットも立っているサンプリング済みトレースを取りこぼします。

将来バージョンへの前方互換性

version は今日 00 で ff は禁止ですが、それ以外をすべて拒否するパーサーは誤りです。仕様は、バージョンがより高くヘッダーが既知の形式以上の長さであれば、トレースを張り直すのではなく解析を試み、認識できるフィールドを読み、余分な末尾データを許容するよう受信側に求めています。このデコーダーもその規則に従い、将来のバージョンは解析に成功し、エラーではなく警告として示されます。

本番で効いてくる tracestate の制限

リストメンバーは最大32件——これは文法上の厳格な上限で、これを超えるとヘッダー自体が無効になり、受信側はそれを破棄します。各キーは最大256文字で、小文字か数字で始まります。Level 2 以降、@ はテナント区切りではなく通常のキー文字です。各値は1〜256文字の印字可能 ASCII で、カンマと等号は含められず、空にもできません。キーの重複は無効ですが、空のリストメンバーは仕様が明示的に認めています——中間装置がエントリーを削除して残った末尾のカンマも、依然として有効なヘッダーです。これとは別に、ベンダーは結合後のヘッダーを最低512文字は伝播させるべきとされ、その予算に収めるために切り詰める際は128文字を超えるエントリーから先に落とすべきとされています——だから饒舌なベンダーのデータほど、簡潔なベンダーより先に消えるのです。

Trace Context のベストプラクティス

フラグはビット AND で判定する

flags == 0x01 ではなく flags & 0x01 と書いてください。8ビットのうち6ビットは将来のために予約されており、そのどれかが実運用に現れた瞬間から、等値比較はサンプリング済みトレースを誤判定し始めます。

オールゼロの ID は壊れたパイプラインとして扱う

許容してよい空値ではありません。ヘッダーを拒否したうえで、トレーサーの初期化に失敗しているか、プレースホルダーを注入しているコンポーネントを探しに行ってください。

sampled ビットが落ちていたら上流を見る

親ベースのサンプラーは呼び出し元の判断を伝播させます。トレースが欠けているなら、自分の設定を調べる前に、サンプリングを切った親 span を送っているサービスを特定してください。

tracestate は短く保つ

32メンバーの上限は文法上の厳格な境界です——超えた時点でヘッダーは無効になります。これとは別に、結合後のヘッダーは512文字までしか伝播が保証されず、切り詰めでは128文字を超えるエントリーから先に落とされます。長い呼び出し連鎖を生き延びてほしいデータは、そもそも tracestate に置くべきではありません。

trace ID を JavaScript の number としてログに出さない

128ビットの trace ID も、64ビットの Datadog 識別子でさえ、Number.MAX_SAFE_INTEGER を超えます。文字列のまま保持し、計算が必要なときだけ BigInt に変換してください。さもないと末尾の桁が静かに壊れます。

traceparent デコーダー よくある質問