フロントエンドとバックエンドのトレースを関連付ける

フロントエンドのオブザーバビリティにおける最終的な目標は、React でのユーザーのクリックからネットワーク、API ハンドラー、サービス呼び出しを経て、遅いレスポンスの原因となったデータベースクエリまでを 1 つにつなぐトレースです。このエンドツーエンドのトレースにより、根本原因を即座に分析できます。

W3C TraceContext 仕様では、traceparent ヘッダーの形式を version-traceId-parentSpanId-flags と定義しています。値の例は次のとおりです：00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01。trace ID は分散トレース全体で共有され、parent span ID はホップごとに変わります。

OTel の fetch インストルメンテーションは、送信されるすべての fetch リクエストに traceparent ヘッダーを自動的に注入します。このヘッダーには現在の trace ID と、親として機能するフロントエンドの fetch span の span ID が含まれているため、バックエンドはフロントエンドの span に関連付けられた子 span を作成できます。

サーバー上では、Node.js/Express 用の OTel HTTP インストルメンテーションが受信した traceparent ヘッダーを読み取り、フロントエンドの fetch span の子 span を作成します。trace ID は保持されるため、Jaeger や Grafana Tempo では、ブラウザー span → Express span → データベース span という一連のチェーン全体を、1 つのウォーターフォール表示で確認できます。

フロントエンドとバックエンドの両方をインストルメンテーションしたら、Jaeger または Grafana Tempo を開き、trace ID で検索します。最上部に React コンポーネントの span、その下に fetch span、続いて Express のルートハンドラー span、さらにデータベースクエリ span が表示され、すべての実行時間と属性を確認できます。

span.setAttribute('user.id', userId) を使用して、React アプリのすべての span に user.id を属性として設定します。バックエンドでも同じことを行います。これで、オブザーバビリティバックエンドを特定のユーザー ID でフィルタリングし、そのユーザーに関するすべてのトレースを表示できるため、特定の顧客が報告した問題を診断できます。

ページの読み込み時に一意のセッション ID を生成し、すべてのフロントエンド span に session.id として設定します。リクエストヘッダーにも含めることで、バックエンドでもバックエンド span に設定できます。セッションの関連付けにより、1 回のセッションでユーザーが行った操作の完全な順序を再構成できます。

Datadog のような商用ツールは、RUM セッションと APM トレースを標準で統合します。Datadog RUM SDK は特定のヘッダー（X-Datadog-Trace-Id）を fetch リクエストに注入し、バックエンドの Datadog APM SDK がそれを読み取って、RUM セッションのリプレイを分散トレースに関連付けます。これにより、セッションのリプレイとトレースを同時に確認できます。

あるユーザーからチェックアウトが遅いという苦情が寄せられたとします。関連付けられたトレースがあれば、オブザーバビリティバックエンドで user.id を検索してチェックアウトのトレースを見つけ、すぐに、2 つの大きなテーブルを結合する 900 ミリ秒のデータベースクエリが遅延の原因だったと確認できます。これはフロントエンドのメトリクスだけでは見えません。

ブラウザーは、CORS の制限や認証情報の漏えいのため、Jaeger などのバックエンドにトレースを直接送信できません。代わりに、OTel Collector をプロキシとして実行します。OTLPTraceExporter の送信先を Collector のエンドポイントに設定し、Collector から Jaeger、Grafana Tempo、その他のバックエンドへ分配します。

フロントエンドのトレースには、意図せず機密データが含まれることがあります。たとえば、URL 内のフォームフィールドの値、span 属性内の PII、ヘッダー内のセッショントークンなどです。span 属性に機密データが含まれていないことを確認するため、インストルメンテーションを見直してください。span.setAttribute は必要最小限に使用し、記録する前に URL のクエリパラメーターをサニタイズします。

W3C TraceContext の traceparent ヘッダーはどのような形式ですか。

フロントエンドとバックエンドのトレースを関連付けると、ユーザーのリクエスト全体をエンドツーエンドで可視化できます。W3C TraceContext の traceparent ヘッダーは、OTel のインストルメンテーションによってブラウザーの fetch span とバックエンドの span を自動的に接続します。対象を絞ったデバッグのために、すべての span に user.id と session.id を付加してください。CORS の問題と認証情報の漏えいを避けるため、ブラウザーとバックエンドの間のプロキシとして OTel Collector を使用します。