upgrade-browser-sdk-v6

Datadog Browser SDK を v6 にアップグレードする

v5 から v6 への体系的な移行ガイドです。手順 1〜6 を順番に実行してください。各手順には、該当するコードを検索するパターンが含まれています。

手順 1：SDK のバージョンを更新する

CDN のセットアップ — スクリプトの src URL を更新します。

v5 のパターン	v6 の置き換え
datadoghq-browser-agent.com/us1/v5/datadog-rum.js	datadoghq-browser-agent.com/us1/v6/datadog-rum.js
datadoghq-browser-agent.com/us1/v5/datadog-logs.js	datadoghq-browser-agent.com/us1/v6/datadog-logs.js
datadoghq-browser-agent.com/us1/v5/datadog-rum-slim.js	datadoghq-browser-agent.com/us1/v6/datadog-rum-slim.js

us1 は使用するサイトに置き換えてください：eu1、us3、us5、ap1、ap2。US1-FED の場合、サイトプレフィックスのないフラットなパターンを使用します：datadog-rum-v6.js、datadog-logs-v6.js、datadog-rum-slim-v6.js。

検索：grep -r "datadoghq-browser-agent.com.*v5" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"

npm のセットアップ — package.json の依存関係を更新します。

"@datadog/browser-rum": "^6.0.0"
"@datadog/browser-logs": "^6.0.0"
"@datadog/browser-rum-slim": "^6.0.0"

次に、パッケージマネージャー（npm install、yarn install など）を実行して、再ビルドしてください。

使用している場合は、フレームワークのインテグレーションも v6 にアップグレードしてください：@datadog/browser-rum-react。

検索：grep -r "@datadog/browser-" --include="package.json" .

手順 2：非推奨のオプションを削除する

Core から削除されたオプション（RUM と Logs の両方に影響）

オプション	対応
useCrossSiteSessionCookie	usePartitionedCrossSiteSessionCookie に置き換えます。

Logs から削除されたオプション

オプション	対応
sendLogsAfterSessionExpiration	削除します。v6 では、セッションの有効期限が切れた後も常にログが送信されます（セッション ID なし）。このオプションは不要になりました。

検索：grep -rn 'useCrossSiteSessionCookie\|sendLogsAfterSessionExpiration' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

手順 3：変更されたデフォルト値を更新する

v6 では、いくつかのデフォルトの動作が変更されています。それぞれ確認し、必要に応じて調整してください。

3a. trackUserInteractions、trackResources、trackLongTasks のデフォルト値が true に変更

v5 では、これらのデフォルト値は false でした。v6 では、初期状態で有効になっています。これは課金には影響しません。

v5 の動作を維持するには、v5 ですでに有効になっていなかったオプションのみを明示的に無効にします。v5 ですでに true だったオプションは変更しないでください。

DD_RUM.init({
  trackUserInteractions: false, // only if not already true in v5
  trackResources: false, // only if not already true in v5
  trackLongTasks: false, // only if not already true in v5
})

3b. traceContextInjection のデフォルト値が "sampled" に変更

v5 では、すべてのリクエストにトレースコンテキストが挿入されていました。v6 では、サンプリングされたトレースにのみ挿入されます。traceSampleRate が 100％（デフォルト）の場合、影響はありません。

v5 の動作を維持するには：

DD_RUM.init({
  traceContextInjection: 'all',
})

3c. tracecontext プロパゲーターに tracestate ヘッダーが追加

tracecontext プロパゲーターは、新たに tracestate ヘッダーも送信するようになりました。サーバーがこのヘッダーを受け入れる必要があります。既存の Access-Control-Allow-Headers に追加してください。リスト全体を置き換えないでください。

# Add tracestate alongside your existing headers
Access-Control-Allow-Headers: <existing-headers>, traceparent, tracestate

3d. site パラメーターは厳密な型付けになりました

site オプションの TypeScript 型がより厳密になりました。標準以外の値を渡すと、型エラーが発生します。標準以外のインテーク URL には、代わりに proxy を使用してください。

検索：grep -rn 'trackUserInteractions\|trackResources\|trackLongTasks\|traceContextInjection\|tracestate\|allowedTracingUrls\|propagatorTypes' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

これらのオプションを省略し、v5 の false デフォルトに依存していたプロジェクトを見つけるため、すべての RUM 初期化呼び出しも検索してください：grep -rn 'DD_RUM\.init\|datadogRum\.init' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte。それぞれの初期化呼び出しで、trackUserInteractions、trackResources、trackLongTasks が明示的に設定されているか確認してください。省略した場合、v6 ではデフォルトで true になります。

ステップ 4：Session Replay の遅延読み込みに対応する

Session Replay は、動的インポートを使用して遅延読み込みされるようになりました。リプレイ対象としてサンプリングされたセッションでのみモジュールが読み込まれるため、それ以外のセッションではバンドルサイズが小さくなります。

npm の設定

バンドラーが動的インポート（コード分割）に対応していることを確認してください。ほとんどの最新バンドラーは対応しています。

• Webpack：［コード分割のドキュメント](https://webpack.js.org/guides/code-splitting/#dynamic-imports)
• Esbuild：［分割オプション](https://esbuild.github.io/api/#splitting)
• Rollup：［コード分割のドキュメント](https://rollupjs.org/tutorial/#code-splitting)
• Parcel：［コード分割のドキュメント](https://parceljs.org/features/code-splitting)

CDN の設定

コードの変更は不要です。記録時に SDK が追加のチャンク（例：datadogRecorder-<hash>-datadog-rum.js）を動的に読み込みます。必要に応じて、チャンクを許可するように CSP の script-src ルールを更新してください。

ステップ 5：動作の変更を確認する（コードの変更は不要ですが、対応が必要な場合があります）

変更	影響	必要に応じた対応
IE11 のサポートを終了	SDK は ES2018 をターゲットにしてビルドされます。ポリフィルは削除されました。	IE11 のサポートが必要な場合は、v5 を引き続き使用してください。
Long Animation Frames が Long Tasks に置き換わる	対応ブラウザーでは、Long Tasks の代わりに Long Animation Frames が収集されます。イベントタイプは引き続き long_task です。	長いタスクイベントの詳細を調べている場合は確認してください。
セッション Cookie の有効期限を 1 年に延長	匿名ユーザーの追跡に対応します。	無効にするには trackAnonymousUser: false を設定してください。
RegExp オブジェクトと Event オブジェクトをサニタイズ	これらはコンテキスト／属性内で、そのままシリアライズされなくなりました。	RegExp オブジェクトまたは Event オブジェクトを渡していた場合は、文字列表現を使用してください。
Webpack の ChunkLoadError を収集しなくなる	SDK のチャンク読み込み失敗によるノイズが減ります。	対応は不要です。

ステップ 6：インフラストラクチャを更新する

• ブラウザーのサポート：ES2018 を基準とします。IE11 はサポートされなくなりました。
• CORS：tracecontext プロパゲーターを使用する場合は、既存の Access-Control-Allow-Headers に tracestate を追加します（リスト全体を置き換えないでください）：Access-Control-Allow-Headers: <existing-headers>, traceparent, tracestate
• CSP：動的に読み込まれる Session Replay チャンク（例：datadogRecorder-*-datadog-rum.js）を script-src ルールで許可します。
• バンドラーの設定：Session Replay の遅延読み込みに必要な動的インポートを、バンドラーがサポートしていることを確認します。

よくある間違い

間違い	問題	対処法
trackUserInteractions、trackResources、trackLongTasks を念のため無効にする	プロジェクトで必要な機能が無効になります。これらは true がデフォルトになりました。通常はこれが望ましい動作です	プロジェクトで不要と明示されている場合にのみ false を設定し、新しいデフォルトを適用するには未設定のままにします
Access-Control-Allow-Headers に tracestate がない	tracecontext プロパゲーターが tracestate ヘッダーを送信するようになったため、クロスオリジンリクエストが CORS によってブロックされます	サーバーの Access-Control-Allow-Headers で traceparent とともに tracestate を追加します
遅延読み込みされる Session Replay チャンクに合わせて CSP の script-src を更新しない	CSP に制限されたページでは録画が失敗しても通知されません。動的チャンクがブロックされます	script-src で datadogRecorder-*-datadog-rum.js を許可します

確認チェックリスト

アップグレード後、次の項目を確認します：

• SDK がコンソールエラーなしで読み込まれる
• 削除されたオプション（useCrossSiteSessionCookie、sendLogsAfterSessionExpiration）への参照がない
• Session Replay の録画が動作している（使用している場合）
• 分散トレーシングが動作している（tracestate ヘッダーによる CORS エラーがない）
• バンドルサイズが小さくなっている（IE11 用ポリフィルが削除されている）
• ロングタスクが引き続き収集される（サポート対象のブラウザーでは Long Animation Frames として収集される）
• site パラメーターの型指定による TypeScript エラーがない