概要
Browser RUM SDK および Browser Logs SDK のメジャーバージョン間で移行するには、このガイドに従ってください。SDK の特徴と機能の詳細については、SDK ドキュメントを参照してください。
v4 から v5 へ
V5 には、以下の変更点などがあります。
- セッションリプレイの新しい構成とプライバシーのデフォルト
- フラストレーションシグナルの自動収集
- パフォーマンスメトリクスの更新
- 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 では使用できなくなりました。
インテークドメイン
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 のコンパイルエラーが解決されます。
セッションリプレイ
セッションリプレイマスキング
セッションリプレイのデフォルトのマスキング設定 defaultPrivacyLevel
が mask-user-input
から mask
に変更されました。これにより、セッションリプレイの記録のすべてのデータがデフォルトで隠され、記録の閲覧が安全になります。詳細については、セッションリプレイブラウザのプライバシーオプションを参照してください。
実行するアクション: センシティブでない HTML コンテンツやユーザーが入力したテキストなど、より多くのマスクされていないデータをセッションリプレイで確認したい場合は、defaultPrivacyLevel
を mask-user-input
または allow
に設定してください。
セッションリプレイ用にサンプリングされたセッションの自動記録
sessionReplaySampleRate
を使ってセッションリプレイ用にサンプリングされたセッションは、セッションの開始時に自動的に記録されます。これは、startSessionReplayRecording()
メソッドを呼び出して記録をキャプチャする必要がないことを意味します。つまり、誤って記録を見逃すことがなくなります。
実行するアクション: 従来の記録動作を使い続け、記録開始のタイミングをカスタマイズしたい場合、startSessionReplayRecordingManually
を true
に設定してください。
セッションが記録をキャプチャした場合のみ、セッションリプレイの料金が生じる
以前のバージョンの SDK では、セッションはサンプリングメカニズムによってセッションリプレイセッションと判断されています。v5 では、セッション中に記録がキャプチャされた場合のみ、セッションはセッションリプレイセッションとしてカウントされます。これにより、セッションリプレイの使用量を追跡しやすくなりました。
アクション不要: この動作は v5 で自動的に有効になります。
セッションリプレイのデフォルトサンプリングレート
v5 ではデフォルトの sessionReplaySampleRate
は 100 ではなく 0 です。サンプリングレートを指定しない場合、リプレイは記録されません。
実行するアクション: セッションリプレイを使うには、sessionReplaySampleRate: 100
(または他のサンプリングレート) で明示的にサンプリングレートを設定してください。
RUM
APM インテグレーション
OpenTelemetry のサポートと利用を促進するために、デフォルトのプロパゲータタイプは datadog
に加えて tracecontext
を含むように変更されました。
取るべきアクション: まだ allowedTracingUrls
の初期化パラメーターで希望するプロパゲータを指定していない場合は、サーバーの Access-Control-Allow-Headers を構成して traceparent
ヘッダーも受け付けるようにしてください。詳細は RUM とトレースの接続を参照してください。
セッションプランフィールド
セッションリプレイの変更に関連して、session.plan
フィールドはセッションイベントでのみ使用可能です。
実行するアクション: セッション以外のイベントに対して、session.plan
フィールドを除外するように、保存してあるモニターやダッシュボードのクエリを更新してください。
フラストレーションシグナルを自動収集
フラストレーションシグナルを含むすべてのユーザーインタラクションを収集するのに、trackUserInteractions: true
を設定するだけでよくなりました。もう trackFrustrations
パラメーターを個別に設定する必要はありません。
実行するアクション: フラストレーションシグナルを追跡するには、trackUserInteractions: true
を設定します。trackFrustrations
パラメーターは削除できます。
フリーズしたページでは、リソースの継続時間が省略される
リソース収集は、例えば、ページがロードされている間にユーザーが別のタブをクリックした場合など、ページがバックグラウンドになったために延長されたリソースの継続時間を省略します。
アクション不要: この動作は v5 で自動的に有効になります。
リソースとロングタスクの追跡
replaySampleRate
または premiumSampleRate
(どちらも非推奨) の代わりに sessionReplaySampleRate
を使用する場合は、リソースとロングタスクを明示的に構成する必要があります。
実行するアクション: これらのイベントを収集するには、trackResources
と trackLongTasks
が true
に設定されていることを確認してください。
リソースメソッド名は大文字
大文字/小文字 (POST と 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 から送信されるのではなく、バックエンドから直接計算されます。
実行するアクション:
view.in_foreground_periods
を beforeSend
コードから削除してください。特定のユースケースでこの属性に依存していた場合は、サポートにお問い合わせください。
beforeSend
パフォーマンスエントリ
beforeSend
コンテキストの performanceEntry
属性が JSON 表現から更新され、パフォーマンスエントリオブジェクトを直接含むようになりました。
エクスポートされた PerformanceEntryRepresentation
型は削除され、標準の PerformanceEntry
型が使用されるようになりました。
実行するアクション: beforeSend
コードでは、PerformanceEntryRepresentation
型の代わりに PerformanceEntry
型を直接使用してください。
ログ
コンソールエラーのプレフィックスを削除
ログメッセージ中の “console error:
” プレフィックスが削除されました。この情報は origin
属性にあります。
実行するアクション: "console error:"
プレフィックスを使用しているモニターやダッシュボードのクエリを更新し、代わりに @origin:console
を使用するようにしてください。
error.origin
の削除
すべてのログに origin
属性が導入されたため、error.origin
は冗長になり削除されました。
実行するアクション: error.origin
を使用しているモニターやダッシュボードのクエリを更新し、代わりに origin
を使用するようにしてください。
メインロガーの切り離し
SDK が実行時エラーやネットワーク、レポート、またはコンソールログを収集するとき、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"
}
}
RUM エラーソース属性
RUM Browser SDK では、addError API で収集されたエラーのソースの特定ができなくなります。この API で収集されたすべてのエラーは、ソース属性が custom
に設定されます。addError API は、コンテキストオブジェクトをその 2 番目のパラメーターとして受容し、エラーに関する追加コンテキストを渡すために使用されます。
削除
RUM API
旧 API | 新 API |
---|
addUserAction | addAction |
初期化オプション
旧オプション | 新オプション |
---|
publicApiKey | clientToken |
datacenter | site |
resourceSampleRate | なし |
TypeScript タイプ
旧タイプ | 新タイプ |
---|
RumUserConfiguration | RumInitConfiguration |
RumRecorderUserConfiguration | RumRecorderInitConfiguration |
LogsUserConfiguration | LogsInitConfiguration |
その他の参考資料