dd-instrument-rum

Datadog Browser RUM の計装

対象範囲のブラウザーアプリケーションのみを計装してください。Datadog APM、トレーシング、LLM Observability、Logs、ソースマップのアップロード、ユーザー識別、Vercel のメタデータ、Shopify、Salesforce、または無関係な Datadog 製品は追加しないでください。

任意の RUM アプリケーション作成を除き、すべての手順で通常のファイル確認、編集、コマンドツールを使用してください。この操作には、references/common-credentials.md の説明に従って CreateRumApplication のみを使用し、Datadog ツール名を決して作り出さないでください。

基本ルール

• 編集前に確認してください。フレームワーク、バージョン、エントリーポイント、コマンド、設定に関するすべての判断は、プロジェクトファイルに基づいてください。
• 該当するリファレンスに記載されているパッケージ名、インポートパス、エクスポートシンボル、init オプションキーをそのままコピーしてください。パッケージのエイリアスに置き換えたり、SDK API を記憶から再現したりしないでください。
• 変更を加える前に簡単なチェックリストを提示し、作業の進行に合わせて更新してください。
• RUM は一度だけ、ブラウザーのライフサイクル上で安全に可能な限り早いタイミングで初期化してください。init() をコンポーネントのレンダー、ライフサイクルフック、ルートハンドラー、または繰り返し実行されるコールバックに配置しないでください。
• 既存の有効な init 設定は維持してください。その init に、不足している互換性のあるフレームワークプラグインの配線をその場で追加してください。競合する init を新たに作成しないでください。
• 既存 init の認証情報に関するガードレール： 有効な RUM init がすでに 1 つある場合、その applicationId、clientToken、site、サービスのタグ、サンプリング、プライバシー、トラッキング、その他すべての既存オプションを変更不可として扱ってください。タスクで提供された認証情報は新しい init のみを対象とし、既存の有効な init の上書きには使用しません。この場合、プラグインの配線を追加するときに認証情報の行を書き換えないでください。
• 必要な認証情報を解決できない場合、site が無効な場合、フレームワークまたはプラグインの前提条件を満たしていない場合、権限が作業を妨げる場合、または競合する複数の init 呼び出しを安全に統合できない場合は、編集せずに停止してください。
• Browser RUM に必要なパッケージのみをインストールしてください。@datadog/browser-rum とすべての @datadog/browser-rum-* インテグレーションパッケージは、同じ正確な SDK バージョンにそろえてください。
• 実際のビルドで使用するマニフェストとロックファイルに依存関係を記録してください。node_modules にたまたま存在するパッケージに依存しないでください。
• アプリケーションの動作、既存のカスタムエラー処理、書式規約、無関係なコードを維持してください。
• 利用可能なファイル編集ツールを使って編集してください。想定したテキストが見つからない場合は、同じ編集を再試行するのではなく、ファイルを読み直して現在の内容に合わせて対応してください。
• プロジェクトのパス、フレームワークの詳細、認証情報、クライアントトークン、RUM アプリケーション ID を永続的なメモリに書き込まないでください。
• 成功を報告する前に、終了するビルドを実行してください。実際に確認していない限り、テレメトリを受信したと主張しないでください。

フェーズ 1：対象を分析する

ブラウザーアプリケーションを特定する

ブラウザーコードを生成するプロジェクトルートを特定してください。モノレポでは、ワークスペース設定、スクリプト、Dockerfile、CI／デプロイ設定を確認し、リポジトリのルートを前提に編集するのではなく、実際のビルドで使われるフロントエンドのマニフェストを見つけてください。編集前に、そのマニフェストのパスとパッケージマネージャーを記録してください。独立したブラウザーアプリケーションが複数候補に挙がり、ユーザーがどれを選ぶか指定していない場合は、どのアプリケーションを計装するか尋ねてください。

Ink CLI などのブラウザー以外のアプリケーションや、HTML／ブラウザービルドのターゲットがないプロジェクトは対象外としてください。

フレームワークとランタイムの構成を判定する

基盤となる UI ライブラリよりメタフレームワークを優先するため、次の順序で依存関係とソースの構成を調べます。

1. nuxt -> Nuxt
2. next -> Next.js。ソースの構成から App Router と Pages Router を判別します
3. @angular/core -> Angular。スタンドアロンブートストラップと NgModule を判別します
4. vue -> Vue
5. svelte または @sveltejs/kit -> Svelte または SvelteKit
6. react -> React
7. 上記に該当せず、ブラウザーのエントリーポイントがある -> 汎用／バニラのブラウザーアプリケーション

以下も判定します。

• フレームワーク、React Router、TanStack Router、Vue Router、Node の正確なバージョン。
• tsconfig.json または TypeScript の依存関係がある場合は TypeScript を使用し、そうでなければ JavaScript を維持します。
• デプロイ対象のマニフェストにある packageManager フィールドを優先し、次に隣接するロックファイルからパッケージマネージャーを判定します。対象は bun.lock または bun.lockb、pnpm-lock.yaml、yarn.lock、package-lock.json です。より強いプロジェクト上の根拠がない場合に限り npm を使用し、パッケージマネージャーを混在させないでください。
• 設定と依存関係からバンドラーを判定します。対象は Vite、Webpack、Rollup、esbuild、Rspack、または Create React App（react-scripts）です。管理されていない HTML は、パッケージ／バンドラーによるビルドが存在しない場合に限り CDN として扱います。
• ファイル名だけでなく、ビルド設定、HTML のスクリプト対象、フレームワークの規約、インポートグラフからブラウザーのエントリーポイントを判定します。
• 通常の終了時に実行するビルド／型チェックコマンド。
• 既存のパブリック環境変数の規約。

references/rum-core.md を読み、続いて該当するフレームワークのリファレンスを正確に 1 つ読みます。

対象	リファレンス
React、React Router、TanStack Router	references/rum-react.md
Next.js App Router または Pages Router	references/rum-nextjs.md
Angular	references/rum-angular.md
Vue	references/rum-vue.md
Nuxt	references/rum-nuxt.md
Svelte、バニラ、汎用 SPA、iframe ホスト型アプリ	references/rum-other-frameworks.md

認証情報を用意したり編集したりする前に、選択したリファレンスの前提条件をすべて確認してください。フレームワークをアップグレードせず、検出したフレームワークのプラグインに互換性がない場合に、コアのみの RUM へ黙ってフォールバックしないでください。

既存の RUM 計測を検出する

依存関係、ビルド、生成物、カバレッジのディレクトリ（node_modules、dist、build、.next、.nuxt、coverage など）を除外して、ソース、HTML、設定ファイルを検索します。

以下を確認します。

• 名前付きバインディングや名前空間バインディングへのリネームも含めた、@datadog/browser-rum からのインポートまたは require。
• @datadog/browser-rum-* の各インテグレーションパッケージからのインポート。
• インポートした datadogRum.init にバインドされた呼び出し。エイリアスやローカルのラッパーモジュールも含みます。
• DD_RUM.init、window.DD_RUM.init、DD_RUM.onReady、Datadog CDN ローダーの URL。
• 既存のプラグイン登録、ルーターラッパー／プロバイダー／コンポーネント、フレームワークのエラーフック。

依存関係が存在するだけでは不十分です。未使用の依存関係である可能性があります。

• init がない場合： 選択したリファレンスに従って 1 つ追加します。
• 有効な init が 1 つある場合： 場所と既存の値をすべて維持します。認証情報の置き換えを解決または適用しないでください。既存の init に、不足している互換性のあるプラグイン／ルーター／エラー関連の配線のみを追加します。
• init が 1 つあり、必須の認証情報／サイトが不足または無効な場合： 停止して無効な設定を報告します。その上に別の init を重ねないでください。
• init 呼び出しが複数ある場合、または npm／CDN の設定が混在している場合： 相互排他的な 1 つの設定であると証明できない限り、停止してすべての場所を報告します。どの設定を優先するか推測しないでください。
• 設定が完全な場合： 変更を加えず、該当する検証は実行します。

フェーズ 2：計装

分析が成功した後にのみ、references/common-credentials.md を通じて認証情報を解決します。分析で有効な既存の初期化が 1 つ見つかった場合は、その既存の認証情報を再利用し、認証情報の置き換えは一切行いません。提供されたタスク認証情報は、新しい初期化を作成する場合にのみ使用できます。その後、次の手順を実行します。

1. 検出されたパッケージマネージャーを使用し、デプロイ済みのフロントエンドマニフェストに基づいて、コア SDK と互換性のあるフレームワークパッケージをインストールします。有効な既存の初期化がある場合は、不足している連携パッケージのみをインストールします。すでに有効な RUM パッケージや設定は、決して置き換えないでください。
2. references/rum-core.md に記載された標準の設定とインストール方法を適用します。有効な既存の初期化がある場合は、同じオブジェクトに不足している互換性のあるフィールドのみを適用します。認証情報や標準オプションのプレースホルダーで、既存の値を上書きしないでください。
3. 選択したフレームワークのリファレンスを適用します。ルーターのトラッキングと、該当する仕組みがある場合は安全なフレームワークエラー連携も含めます。
4. 同じパッケージマネージャーでロックファイルを更新します。生成されたロックファイルを手作業で編集してはいけません。
5. lint:fix、fix、format などのマニフェスト内スクリプトと、ESLint／Prettier の設定から、適用されているフォーマット方法を検出します。この作業で変更したファイルに限り、プロジェクトのフォーマッターまたは修正コマンドを実行します。

allowedTracingUrls やバックエンド／CORS／トレーシングの設定は追加しないでください。これらは APM のオンボーディングワークフローに属します。

フェーズ 3：検証と報告

references/common-verify-report.md に従います。成功を報告する前に、編集前のプロジェクトと最終差分を確認します。有効な既存の初期化が見つかった場合は、認証情報 2 つを含む既存の初期化値がすべてバイト単位で変更されていないこと、また、設定に関する変更が不足していた連携設定の追加のみであること（および厳密に必要な依存関係／ロックファイルの変更があればその変更）を検証します。既存の値が変更されていた場合は、成功を報告する前に元に戻します。必須パッケージが保存され、生成された設定に初期化がちょうど 1 つ含まれ、通常のビルドが成功しない限り、成功を報告してはいけません。