ブラウザーからOpenTelemetryトレースを取得する

ブラウザー向けのOpenTelemetry JavaScript SDKはいくつかのパッケージで構成されています。@opentelemetry/sdk-trace-webは中核となるトレース実装を、@opentelemetry/instrumentation-fetchはすべてのfetch API呼び出しに対するスパンを自動的に作成する機能を、@opentelemetry/exporter-trace-otlp-httpはスパンをコレクターに送信する機能を提供します。

TracerProviderは、OpenTelemetryの中心的な設定オブジェクトです。完了したスパンをどう処理するかを決めるSpanProcessorの一覧、アプリケーションを説明するリソース（サービス名やバージョン）、サンプリング設定を保持します。

BatchSpanProcessorは、完了したスパンをメモリ上に集め、各スパンを個別に送信するのではなく、バッチ単位でエクスポートします。これによりコレクターへのHTTPリクエスト数を大幅に減らし、ブラウザーのパフォーマンスを向上させるとともに、OTelコレクターのエンドポイントへの負荷を軽減できます。

OTLPTraceExporterは、バッチ化したスパンをOpenTelemetry互換のコレクターへ、JSONまたはprotobuf形式のHTTPで送信します。コレクターのURL（例: OTel Collectorプロキシのエンドポイント）を設定すれば、エクスポーターがシリアライズと再試行のロジックを自動的に処理します。

Spanは、トレース内の1つの作業単位を表します。たとえば、コンポーネントのマウント、API呼び出し、ユーザー操作などです。スパンには、名前、開始時刻、終了時刻、ステータス（OKまたはERROR）、キーと値の属性が含まれます。関連するスパンは、共通のトレースIDと親子関係によって結び付けられます。

provider.getTracer('react-app')でトレーサーを作成し、tracer.startSpan('component-mount')でスパンを開始します。処理が完了したらspan.end()を呼び出して終了時刻を記録します。必ずスパンを終了してください。終了されていないスパンはメモリを消費し、オブザーバビリティのバックエンドに不完全なデータを生成します。

属性を使うと、コンテキストデータでスパンを補足できます。たとえば、span.setAttribute('user.id', userId)やspan.setAttribute('route', location.pathname)のように指定します。属性はオブザーバビリティのバックエンドで検索できるため、「ユーザー42の遅いスパンをすべて表示」や「/checkoutルートのすべてのエラーを表示」といったクエリを実行できます。

@opentelemetry/instrumentation-fetchはグローバルのfetch関数にモンキーパッチを適用し、すべての外向きHTTPリクエストに対するスパンを自動的に作成します。既存のfetch呼び出しを変更しなくても、スパンにはURL、メソッド、HTTPステータスコード、所要時間が記録されます。

fetch のインストルメンテーションが送信リクエスト用の span を作成すると、W3C TraceContext の traceparent ヘッダーをリクエストに注入します。受信側のバックエンドはこのヘッダーを読み取り、同じトレースを継続します。これにより、ブラウザーとサーバーにまたがる接続されたトレースが作成されます。

OTel の初期化は、コンポーネントがマウントされる前に行う必要があります。通常はアプリのエントリーファイル（main.tsx）で、ReactDOM.createRoot の呼び出し前に行います。プロバイダーを作成し、プロセッサーとエクスポーターを登録してから、provider.register() を呼び出してグローバルな TracerProvider にします。

トラフィックの多いアプリでユーザー操作をすべて記録すると、膨大な量のトレースデータが生成されます。TracerProvider で TraceIdRatioBased sampler（例：トレースの 10% をサンプリング）を設定し、データ量を削減します。ParentBased sampler を使用して、エラートレースは常に 100% サンプリングし、エラーを見逃さないようにしてください。

ブラウザーアプリケーションでは、SimpleSpanProcessor ではなく BatchSpanProcessor を使用するのはなぜですか。

OpenTelemetry JavaScript SDK は、TracerProvider、BatchSpanProcessor、OTLPTraceExporter を使用してブラウザーをインストルメンテーションします。span は作業単位を表し、属性によって情報を付加できます。fetch のインストルメンテーションは API 呼び出し用の span を自動的に作成し、エンドツーエンドの分散トレーシングのために W3C TraceContext ヘッダーを注入します。早期に初期化し、適切にサンプリングし、クリーンなトレースデータを維持するために必ず span を終了してください。