upgrade-browser-sdk-v5

Name: upgrade-browser-sdk-v5
Author: datadog-labs

github.com/datadog-labs開発18057 回インストール6 日前に更新

リポジトリ

upgrade-browser-sdk-v5 について

upgrade-browser-sdk-v5は、Datadog Browser SDKをv4からv5へ更新するチーム向けの移行スキルです。バージョン更新、オプションやAPIの変更、動作とインフラ要件を順に確認できます。

主な機能

017段階でv4からv5への移行を案内
02CDNとnpmのバージョン更新に対応
03非推奨オプションとAPIの置き換えを提示
04Session Replayの設定変更を説明
05CSPとCORSの調整を網羅

活用シーン

01Browser SDK v5への更新計画
02非推奨設定やAPI使用箇所の特定
03Session Replayの動作変更の確認
04トレースとデータ受信環境の更新準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/datadog-labs/agent-skills --skill upgrade-browser-sdk-v5

インストール後、Claude Code で/upgrade-browser-sdk-v5を入力して読み込まれたか確認します。

詳細

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

v4 から v5 への体系的な移行ガイドです。ステップ 1〜7 を順番に進めてください。各ステップには、該当するコードを検索するためのパターンが記載されています。

ステップ 1：SDK のバージョンを更新する

CDN の設定 — スクリプトの src URL を更新します。

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

us1 をご利用のサイトに置き換えてください：eu1、us3、us5、ap1。US1-FED の場合、サイトのプレフィックスがないフラットなパターンを使用します：datadog-rum-v5.js、datadog-logs-v5.js、datadog-rum-slim-v5.js。注：v5 では AP2 を利用できません。AP2 が必要な場合は、先に v6 にアップグレードしてください。

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

npm の設定 — package.json の依存関係を更新します。

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

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

フレームワーク連携を使用している場合は、それらも v5 にアップグレードしてください：@datadog/browser-rum-react。

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

ステップ 2：非推奨の初期化パラメーターを置き換える

以下の v4 のパラメーター名は、v5 では使用できなくなりました。置き換えてください。

非推奨のパラメーター（v4）	置き換え後（v5）
`proxyUrl`	`proxy`
`sampleRate`	`sessionSampleRate`
`allowedTracingOrigins`	`allowedTracingUrls`
`tracingSampleRate`	`traceSampleRate`
`trackInteractions`	`trackUserInteractions`
`premiumSampleRate`	`sessionReplaySampleRate`
`replaySampleRate`	`sessionReplaySampleRate`

注：sampleRate は幅広く一致します。初期化設定オブジェクトを確認してください。セッションのサンプリングレートには、v5 では sessionSampleRate を使用します。

ステップ 3：非推奨のパブリック API を置き換える

以下の v4 API メソッド名は、v5 では使用できなくなりました。

RUM API

非推奨の API（v4）	置き換え後（v5）
`DD_RUM.removeUser`	`DD_RUM.clearUser`
`DD_RUM.addRumGlobalContext`	`DD_RUM.setGlobalContextProperty`
`DD_RUM.removeRumGlobalContext`	`DD_RUM.removeGlobalContextProperty`
`DD_RUM.getRumGlobalContext`	`DD_RUM.getGlobalContext`
`DD_RUM.setRumGlobalContext`	`DD_RUM.setGlobalContext`

ログ API

非推奨の API（v4）	置き換え後の API（v5）
`DD_LOGS.addLoggerGlobalContext`	`DD_LOGS.setGlobalContextProperty`
`DD_LOGS.removeLoggerGlobalContext`	`DD_LOGS.removeGlobalContextProperty`
`DD_LOGS.getLoggerGlobalContext`	`DD_LOGS.getGlobalContext`
`DD_LOGS.setLoggerGlobalContext`	`DD_LOGS.setGlobalContext`
`logger.addContext`	`logger.setContextProperty`
`logger.removeContext`	`logger.removeContextProperty`

ステップ 4：Session Replay の設定を更新する

v5 では Session Replay の複数のデフォルト値と動作が変更されています。

4a. `defaultPrivacyLevel` が `"mask"` に変更

v4 のデフォルトは mask-user-input でした。v5 では、すべてのコンテンツがデフォルトでマスクされます。

v4 の動作（ユーザー入力のみをマスク）を維持するには：

DD_RUM.init({
  defaultPrivacyLevel: 'mask-user-input',
})

4b. 録画が自動的に開始

Session Replay の対象としてサンプリングされたセッションは、自動的に録画されるようになりました。startSessionReplayRecording() を呼び出す必要はありません。

v4 の動作（録画を手動で開始）を維持するには：

DD_RUM.init({
  startSessionReplayRecordingManually: true,
})

4c. `sessionReplaySampleRate` のデフォルトが `0` に変更

v4 のデフォルトのリプレイサンプルレートは 100 でした。v5 では 0 になり、明示的に設定しない限りリプレイは記録されません。

対応：初期化設定で sessionReplaySampleRate が明示的に設定されていることを確認してください。

DD_RUM.init({
  sessionReplaySampleRate: 100, // or your desired rate
})

4d. `trackResources` と `trackLongTasks` を明示的に設定する必要があります

削除された replaySampleRate または premiumSampleRate の代わりに sessionReplaySampleRate を使用する場合、リソースと長時間タスクはデフォルトで収集されなくなりました。明示的に有効にしてください。ただし、v4 の設定で意図的に false に設定していた場合は除きます。

DD_RUM.init({
  sessionReplaySampleRate: 100,
  trackResources: true, // omit if v4 explicitly had trackResources: false
  trackLongTasks: true, // omit if v4 explicitly had trackLongTasks: false
})

検索：grep -rn 'sessionReplaySampleRate\|startSessionReplayRecording\|defaultPrivacyLevel\|trackResources\|trackLongTasks' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

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

ステップ 5：変更された API と動作を更新する

5a. `beforeSend` はブール値を返す必要があります

beforeSend コールバック関数は、イベントを保持する場合は true、破棄する場合は false を返してください。値を返さない場合、イベントは保持されます。これにより、TypeScript のコンパイルエラーが解消されます。

beforeSend: (event, context) => {
  // return true to keep, false to discard
  return true
}

5b. `beforeSend` のアクションコンテキスト：`context.event` → `context.events`

フラストレーションシグナルでは、1 つのアクションイベントに複数の DOM イベントが関連付けられることがあります。context.event は context.events（配列）に置き換えられます。

// v4
beforeSend: (event, context) => {
  if (event.type === 'action') {
    const domEvent = context.event
  }
}

// v5
beforeSend: (event, context) => {
  if (event.type === 'action') {
    const domEvents = context.events // array
  }
}

5c. `beforeSend` のパフォーマンスエントリが `PerformanceEntry` オブジェクトに変更

beforeSend コンテキスト内の performanceEntry は、JSON 表現ではなく、生の PerformanceEntry オブジェクトになりました。PerformanceEntryRepresentation 型は削除されました。

5d. XHR の `beforeSend` コンテキストから `startTime` を削除

XHR リソースの beforeSend コンテキストから context.startTime プロパティが削除されました。代わりに performanceEntry を使用してください。

5e. `beforeSend` から `view.in_foreground_periods` を削除

この属性はバックエンドで計算されるようになりました。view.in_foreground_periods にアクセスする beforeSend のコードは削除してください。

5f. 不満のシグナルが自動的に収集される

trackUserInteractions: true を設定すると、不満のシグナルを含むすべてのユーザーインタラクションが収集されます。trackFrustrations パラメーターは不要になりました。

5g. リソースのメソッド名は大文字

リソースの method フィールドは常に大文字になりました（例：GET、POST）。resource.method でフィルタリングしているダッシュボードやモニターを更新してください。

5h. `session.plan` フィールドが削除

session.plan フィールド（lite／premium）は v5 で削除され、どのイベントタイプでも出力されません。session.plan によるダッシュボードやモニターのフィルターは、以下の新しいリプレイフィールドに置き換えてください。

@session.sampled_for_replay:true — セッションが Session Replay 用にサンプリングされた
@session.has_replay:true — セッションに実際のリプレイ録画がある

検索：grep -rn 'beforeSend\|trackFrustrations\|PerformanceEntryRepresentation\|in_foreground_periods\|context\.event\b\|startTime' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

ステップ 6：信頼済みイベントに対応する

v5 はユーザーが生成した（信頼済み）イベントのみをリッスンします。スクリプトで生成されたイベントはデフォルトで無視されます。

プログラムからのイベント（例：dispatchEvent）を利用している場合は、__ddIsTrusted 属性を追加してください。

// JavaScript
const click = new Event('click')
click.__ddIsTrusted = true
document.dispatchEvent(click)

// TypeScript
const click = new Event('click') as Event & { __ddIsTrusted?: boolean }
click.__ddIsTrusted = true
document.dispatchEvent(click)

または、すべての信頼されていないイベントをグローバルに許可します。

DD_RUM.init({
  allowUntrustedEvents: true,
})

検索：grep -rn 'dispatchEvent\|new Event\|new MouseEvent\|new KeyboardEvent\|\.click()' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

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

CSP の `connect-src` ドメインが変更

v5 は新しいインテークドメインにデータを送信します。Content Security Policy を更新してください。

Datadog サイト	新しい `connect-src` ドメイン
US1	`https://browser-intake-datadoghq.com`
US3	`https://browser-intake-us3-datadoghq.com`
US5	`https://browser-intake-us5-datadoghq.com`
EU1	`https://browser-intake-datadoghq.eu`
US1-FED	`https://browser-intake-ddog-gov.com`
US2-FED	`https://browser-intake-us2-ddog-gov.com`
AP1	`https://browser-intake-ap1-datadoghq.com`

分散トレーシング用の CORS ヘッダー

v5 では tracecontext がデフォルトの伝搬方式として追加されます。allowedTracingUrls を使用している場合、サーバーは traceparent ヘッダーを受け入れる必要があります。既存の Access-Control-Allow-Headers に追加してください。リスト全体を置き換えないでください。

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

ログ：`error.origin` を削除

error.origin を使用しているダッシュボードやモニターを更新し、代わりに origin を使用してください。

ログ：コンソールエラーのプレフィックスを削除

ログメッセージから "console error:" のプレフィックスが削除されました。このプレフィックスを使用しているクエリを更新し、代わりに @origin:console を使用してください。

ログ：メインロガーを分離

ランタイムエラー、ネットワークログ、レポートログ、コンソールログは、メインロガーのコンテキスト、レベル、ハンドラーを継承しなくなりました。代わりに、グローバルコンテキストと専用の初期化パラメーターを使用してください。

この継承に依存していた可能性があるメインロガーの設定を検索してください：grep -rn 'DD_LOGS\.logger\.setLevel\|DD_LOGS\.logger\.setHandler\|DD_LOGS\.logger\.setContext\|DD_LOGS\.logger\.setContextProperty' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"。各一致箇所について、その設定がメインロガーのみに対して意図されたものか確認してください。設定はランタイムエラー、ネットワークログ、コンソールログには影響しなくなります。

よくある間違い

間違い	問題点	修正方法
`trackResources` と `trackLongTasks` を有効にせずに `sessionReplaySampleRate > 0` を設定する	リソースとロングタスクが通知なく収集されません — `sessionReplaySampleRate` を使用しても、デフォルトで `true` にはなりません	`sessionReplaySampleRate` が 0 以外の場合は、必ず `trackResources: true, trackLongTasks: true` を併せて追加してください
アクションイベントの `beforeSend` で `context.events` ではなく `context.event` を使用する	アクションコンテキストのプロパティ名が変更されています — `context.event` は `undefined` になり、DOM イベントの詳細が失われます	`context.events`（配列）に更新してください。関連するすべての DOM イベントが必要な場合は、配列を反復処理してください
CSP の `connect-src` を新しい v5 の取り込みドメインに更新しない	SDK がデータの送信に失敗します — 古い取り込みドメインは無効になっています	`connect-src` をサイトの v5 取り込みドメインに更新してください（ステップ 7 を参照）

検証チェックリスト

アップグレード後、次の項目を確認してください。

Markdown 対応

ログインしてコメント

基本情報

作者: datadog-labs
リポジトリ: datadog-labs/agent-skills
カテゴリ: 開発
インストール数: 57
GitHub スター: 180

問題を報告