RUM ブラウザ SDK のアップグレード

Docs > RUM & セッションリプレイ > リアルユーザーモニタリングおよびセッションリプレイについてのガイド > RUM ブラウザ SDK のアップグレード

概要

このガイドに従って、Browser RUM および Browser Logs SDK のメジャーバージョン間で移行してください。SDK の特徴と機能の詳細については、SDK ドキュメントを参照してください。

v4 から v5 への移行

v5 では、以下の変更点などが導入されています。

Session Replay の新しい構成とプライバシーのデフォルト設定
フラストレーションシグナルの自動収集
パフォーマンスメトリクスの更新
SDK パラメーターと API の更新

SDK をアップグレードする際には、以下の変更点にご注意ください。変更点は、影響の分野ごとにグループ化されています。

一般

SDK 初期化パラメーター

取るべきアクション: 非推奨パラメーターを v5 の新しいパラメーターに置き換えてください。旧パラメーター名は v5 では使用できません。

非推奨パラメーター名 (v4 以前)	新しいパラメーター名 (v5)
proxyUrl	プロキシ
sampleRate	sessionSampleRate
allowedTracingOrigins	allowedTracingUrls
tracingSampleRate	traceSampleRate
trackInteractions	trackUserInteractions
premiumSampleRate	sessionReplaySampleRate
replaySampleRate	sessionReplaySampleRate

パブリック API

取るべきアクション: 非推奨 API を新しい API に置き換えてください。旧 API は v5 では使用できません。

非推奨パラメーター名 (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
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

インテークドメイン

v5 では、以前のバージョンとは異なるインテークドメインにデータが送信されます。

取るべきアクション: Content Security Policy (CSP) の connect-src エントリを新しいドメインに更新してください。

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

信頼されているイベント

不正または不正確なデータの収集を避けるために、v5 ではユーザーのアクションによって生成されたイベントのみをリッスンし、スクリプトによって生成されたイベントは無視されます。詳細については、信頼されているイベントを参照してください。

取るべきアクション: プログラムによるイベントも SDK に考慮させたい場合は、以下のように __ddIsTrusted 属性を追加してください。

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

取るべきアクション: 例えば、自動化された UI テスト環境などでプログラムによるイベントに大きく依存している場合は、allowUntrustedEvents: true を設定して、すべての信頼されていないイベントを許可することができます。

beforeSend の戻り値の型

beforeSend コールバック関数はブール値を返す必要があります。

beforeSend(event: any, context?: any) => boolean

実装は変更されていませんが、値が返されない場合でもイベントは破棄されません。

取るべきアクション: beforeSend が true を返すとイベントは保持され、false を返すと破棄されることを確認してください。これにより、関連する TypeScript のコンパイルエラーが解決されます。

セッションリプレイ

セッションリプレイマスキング

Session Replay のデフォルトのマスキング設定 defaultPrivacyLevel が mask-user-input から mask に変更されました。これにより、Session Replay 記録の全データがデフォルトで非表示になり、閲覧時に機密性の高い情報が見えなくなります。詳細は Session Replay ブラウザプライバシーオプションを参照してください。

取るべきアクション: Session Replay で機密性のない HTML コンテンツやユーザーが入力したテキストなどのマスクされていないデータを表示したい場合は、defaultPrivacyLevel を mask-user-input または allow に設定してください。

Session Replay 用にサンプリングされたセッションの自動記録

sessionReplaySampleRate を使用して Session Replay 用にサンプリングされたセッションは、セッションの開始時に自動的に記録されます。つまり、記録をキャプチャするために startSessionReplayRecording() メソッドを呼び出す必要はありません。言い換えると、記録の取りこぼしを防ぐことができます。

取るべきアクション: 古い記録方法を継続し、記録の開始タイミングをカスタマイズしたい場合は、startSessionReplayRecordingManually を true に設定してください。

セッションが記録をキャプチャした場合にのみ Session Replay の料金が発生する

以前のバージョンの SDK では、セッションはサンプリングメカニズムによってセッションリプレイセッションと判断されています。v5 では、セッション中に記録がキャプチャされた場合のみ、セッションはセッションリプレイセッションとしてカウントされます。これにより、セッションリプレイの使用量を追跡しやすくなりました。

アクションは必要ありません: この動作は v5 で自動的に有効になります。

デフォルトの Session Replay サンプリングレート

v5 では、デフォルトの sessionReplaySampleRate は 100 ではなく 0 です。サンプリングレートを指定しないと、リプレイは記録されません。

取るべきアクション: Session Replay を使用するには、sessionReplaySampleRate: 100 (または他のサンプリングレート) を明示的に設定してください。

RUM

APM インテグレーション

OpenTelemetry のサポートと利用を促進するために、デフォルトのプロパゲータタイプに tracecontext が datadog に加えて追加されました。

取るべきアクション: まだ allowedTracingUrls の初期化パラメーターで希望するプロパゲータを指定していない場合は、サーバーの Access-Control-Allow-Headers を構成して traceparent ヘッダーも受け付けるようにしてください。詳細は RUM とトレースの接続を参照してください。

セッションプランフィールド

Session Replay の変更に伴い、session.plan フィールドはセッションイベントでのみ利用可能です。

取るべきアクション: 保存しているモニターやダッシュボードのクエリを更新し、非セッションイベントの session.plan フィールドを除外してください。

フラストレーションシグナルが自動的に収集される

フラストレーションシグナルを含むすべてのユーザーインタラクションを収集するには、trackUserInteractions: true を設定するだけです。trackFrustrations パラメーターを個別に設定する必要はありません。

取るべきアクション: フラストレーションシグナルを追跡するには、trackUserInteractions: true を設定してください。trackFrustrations パラメーターは削除しても構いません。

フリーズしたページではリソースの継続時間が省略される

ページがバックグラウンドになったために延長されたリソースの持続時間は、リソースコレクションで省略されます。例えば、ページの読み込み中にユーザーが別のタブをクリックした場合などです。

アクションは必要ありません: この動作は v5 で自動的に有効になります。

リソースとロングタスクの追跡

replaySampleRate や premiumSampleRate (どちらも非推奨) の代わりに sessionReplaySampleRate を使用する場合、リソースとロングタスクを明示的に構成する必要があります。

取るべきアクション: これらのイベントを収集するには、trackResources と trackLongTasks が true に設定されていることを確認してください。

リソースメソッド名が大文字

大文字と小文字の違い (POST vs post) によって同じメソッド名が異なる値として扱われるのを避けるため、メソッド名は一貫して大文字で送信されるようになりました。

取るべきアクション: モニターやダッシュボードのクエリを更新し、resource.method フィールドに大文字の値を使用してください。

beforeSend アクションイベント

beforeSend API は、収集したイベントのコンテキスト情報へのアクセスを許可します (RUM データの情報付加と管理を参照)。

フラストレーションシグナルの導入により、アクションイベントは複数の DOM イベントに関連付けることができます。

この更新に伴い、context.event 属性は削除され、context.events 属性が使用されるようになりました。

取るべきアクション: beforeSend のコードを更新し、context.event の代わりに context.events を使用してください。

beforeSend: (event, context) => {
  if (event.type === 'action' && event.action.type === 'click') {
    // アクションイベントに関連するブラウザイベントにアクセス
    // 以前は単一イベント: context.event
    // 現在は複数イベント: context.events
  }
}

beforeSend のフォアグラウンド期間

view.in_foreground_periods 属性は SDK から送信されるのではなく、バックエンドで直接計算されます。

取るべきアクション: beforeSend のコードから view.in_foreground_periods を削除してください。特定のユースケースでこの属性に依存していた場合は、サポートにお問い合わせください。

beforeSend パフォーマンスエントリ

beforeSend コンテキストの performanceEntry 属性が JSON 表現から更新され、パフォーマンスエントリオブジェクトを直接含むようになりました。

エクスポートされた PerformanceEntryRepresentation 型は削除され、標準の PerformanceEntry 型が使用されるようになりました。

取るべきアクション: beforeSend のコードでは PerformanceEntryRepresentation 型の代わりに PerformanceEntry 型を直接使用してください。

Logs

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

ログメッセージの “console error:” プレフィックスが削除されました。この情報は origin 属性で確認できます。

取るべきアクション: "console error:" プレフィックスを使用しているモニターやダッシュボードのクエリを更新し、代わりに @origin:console を使用してください。

error.origin を削除

すべてのログに origin 属性が導入されたため、error.origin は冗長となり、削除されました。

取るべきアクション: error.origin を使用しているモニターやダッシュボードのクエリを更新し、代わりに origin を使用してください。

メインロガーを分離

SDK がランタイムエラーやネットワーク、レポート、コンソールログを収集する際に、メインロガー (DD_LOGS.logger) に固有のコンテキストを追加せず、そのロガーに設定されたレベルやハンドラーを使用しません。

取るべきアクション: 非ロガーのログを除外するためにメインロガーのレベルに依存していた場合、代わりに専用の初期化パラメーターを使用してください。

取るべきアクション: 非ロガーのログにコンテキストを追加するためにメインロガーのコンテキストに依存していた場合、代わりにグローバルコンテキストを使用してください。

v3〜v4

v4 では、RUM と Logs Browser SDK にいくつかの重大な変更が加えられました。

変更

取込先 URL

RUM Browser SDK のデータ送信先 URL が変更になりました。コンテンツセキュリティポリシーが最新であることを確認してください。

最小限の Typescript のバージョンサポート

RUM Browser SDK v4 は、v3.8.2 より前の TypeScript と互換性がありません。TypeScript を使用する場合は、バージョンが v3.8.2 以上であることを確認してください。

タグの構文

version、env、serviceの初期化パラメーターは、Datadog にタグとして送信されます。RUM Browser SDK は、複数のタグが生成されないように、それらをわずかにサニタイズし、それらの値がタグの要件構文に適合しない場合は警告を表示します。

初期化パラメーターの型の厳格化

TypeScript の初期化パラメーターを表す型はより厳しくなっており、以前受け取ったサポートされていないパラメーターは拒否されることがあります。もし型チェックのエラーが発生した場合は、サポートされている初期化パラメーターを指定していることを確認してください。

プライバシーオプションの優先順位

複数のプライバシーオプションが同じ要素に指定されている場合、Datadog は最も制限の厳しいオプションを適用し、機密データの予期せぬ漏えいを回避します。例えば、同じ要素に dd-privacy-allow と dd-privacy-hidden の両方のクラスが指定されている場合、allow の代わりに hidden が適用されます。

アクション名計算

RUM Browser SDK は、アクション名を計算する際に、data-dd-action-name 属性を持つ子要素のテキストを内側のテキストから削除しています。

例えば、次の container 要素の場合、以前は計算されるアクション名は Container sensitive data でしたが、v4 では計算されるアクション名は Container になります。

<div id="container">
  Container
  <div data-dd-action-name="sensitive">sensitive data</div>
</div>

削除

XHR _datadog_xhr フィールド

RUM Browser SDK は、以前は XMLHttpRequest オブジェクトの内部状態を表す _datadog_xhr プロパティを使用していました。このプロパティは、外部で使用されることを想定していなかったため、代替することなく削除されました。

proxyHost 初期化パラメーター

初期化パラメーター proxyHost は削除されました。代わりに初期化パラメーター proxyUrl を使用してください。

プライバシーオプション対応

プライバシーオプションの input-ignored と input-masked は無効となりました。代わりに mask-user-input プライバシーオプションを使用してください。

具体的には、以下のように置き換えてください。

dd-privacy-input-ignored および dd-privacy-input-masked クラス名を dd-privacy-mask-user-input に置き換えます。
dd-privacy="input-masked" および dd-privacy="input-ignored" 属性値を dd-privacy="mask-user-input" に置き換えます。

v2〜v3

Browser SDK v3 に Session Replay が新登場。この大きなバージョンアップデートにより、RUM および Logs Browser SDK が大きく変わります。

変更

RUM エラー

RUM Browser SDK では、失敗した XHR および Fetch 呼び出しに対する RUM エラーが作成されなくなります。このような失敗したネットワークリクエストは、依然として RUM リソースとして収集され、ステータスコード属性を含みます。

引き続き、失敗したネットワークリクエストを RUM エラーとして表示するには、Datadog では beforeSend API を使用したリソースの傍受、status_code プロパティのチェック、そして addError API を使用したエラーの手動送信をおすすめします。

beforeSend: (event) => {
    if (event.type === 'resource' && event.resource.status_code >= 500) {
        datadogRum.addError(`${event.resource.method} ${event.resource.url} ${event.resource.status_code}`); // "GET https://www.example.com/ 504"
    }
}