RUM データとコンテキストの変更

機能フラグ追跡のベータ版に参加しよう！

機能フラグで RUM データを補強し、パフォーマンス監視や行動の変化を可視化するには、機能フラグ追跡の非公開ベータ版に参加しましょう。アクセス権をリクエストするには、Datadog サポート (support@datadoghq.com) までご連絡ください。

概要

RUM によって収集されたデータを変更して、次のニーズをサポートするには、さまざまな方法があります。

個人を特定できる情報などの機密データを保護します。
サポートを支援するために、ユーザーセッションをそのユーザーの内部 ID に接続します。
データをサンプリングすることにより、収集する RUM データの量を削減します。
データの送信元について、デフォルトの属性が提供するものよりも多くのコンテキストを提供します。

デフォルトの RUM ビュー名をオーバーライドする

RUM SDK は、ユーザーが新しいページにアクセスするたびに、またはページの URL が変更されたときに (シングルページアプリケーションの場合)、ビューイベントを自動的に生成します。ビュー名は現在のページの URL から計算され、可変英数字 ID は自動的に削除されます。たとえば、/dashboard/1234 は /dashboard/? になります。

バージョン 2.17.0 からは、trackViewsManually オプションでビューイベントを手動で追跡することにより、ビュー名を追加して、チームが所有する専用サービスに割り当てることができます。

RUM ブラウザ SDK を初期化する際に、trackViewsManually を true に設定します。

import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    ...,
    trackViewsManually: true,
    ...
});

DD_RUM.onReady(function() {
    DD_RUM.init({
        ...,
        trackViewsManually: true,
        ...
    })
})

window.DD_RUM &&
    window.DD_RUM.init({
        ...,
        trackViewsManually: true,
        ...
    });

新しいページまたはルート変更 (単一ページアプリケーションの場合) ごとにビューを開始する必要があります。RUM データは、ビューの開始時に収集されます。オプションで、関連するビュー名、サービス名、およびバージョンを定義します。
- ビュー: デフォルトは、ページの URL パスです。
- サービス: デフォルトは、RUM アプリケーションの作成時に指定されたデフォルトのサービスです。
- バージョン: デフォルトは、RUM アプリケーションの作成時に指定されたデフォルトのバージョンです。
詳しくは、ブラウザモニタリングの設定をご覧ください。

次の例は、RUM アプリケーションの checkout ページにおけるページビューを手動で追跡するものです。ビュー名には checkout を使用し、purchase サービスとバージョン 1.2.3 を関連付けます。

datadogRum.startView({
  name: 'checkout',
  service: 'purchase',
  version: '1.2.3'
})

DD_RUM.onReady(function() {
    DD_RUM.startView({
      name: 'checkout',
      service: 'purchase',
      version: '1.2.3'
    })
})

window.DD_RUM && window.DD_RUM.startView({
  name: 'checkout',
  service: 'purchase',
  version: '1.2.3'
})

React、Angular、Vue、またはその他のフロントエンドフレームワークを使用している場合、Datadog はフレームワークルーターレベルで startView ロジックを実装することをお勧めします。

RUM データを強化および制御する

RUM ブラウザ SDK は RUM イベントをキャプチャし、それらの主な属性を設定します。beforeSend コールバック関数を使用すると、RUM ブラウザ SDK によって収集されたイベントが Datadog に送信される前に、そのすべてのイベントにアクセスできます。

RUM イベントをインターセプトすると、次のことが可能になります。

追加のコンテキスト属性で RUM イベントを強化する
RUM イベントを変更して、コンテンツを変更したり、機密性の高いシーケンスを編集したりします (編集可能なプロパティのリストを参照してください)
選択した RUM イベントを破棄する

バージョン 2.13.0 以降、beforeSend は 2 つの引数を取ります。RUM ブラウザ SDK によって生成された event と、RUM イベントの作成をトリガーした context です。

function beforeSend(event, context)

潜在的な context 値は次のとおりです。

RUM イベントタイプ	コンテキスト
ビュー	場所
アクション	イベント
リソース (XHR)	XMLHttpRequest と PerformanceResourceTiming
リソース (フェッチ)	リクエスト、リソース、PerformanceResourceTiming
リソース (その他)	PerformanceResourceTiming
Error	エラー
ロングタスク	PerformanceLongTaskTiming

詳細については、RUM データの強化と制御ガイドを参照してください。

RUM イベントを強化する

グローバルコンテキスト API で追加された属性に加えて、イベントにコンテキスト属性を追加できます。たとえば、フェッチ応答オブジェクトから抽出されたデータで RUM リソースイベントにタグを付けます。

import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    ...,
    beforeSend: (event, context) => {
        // RUM リソースの応答ヘッダーを収集します
        if (event.type === 'resource' && event.resource.type === 'fetch') {
            event.context = {...event.context, responseHeaders: context.response.headers}
        }
    },
    ...
});

DD_RUM.onReady(function() {
    DD_RUM.init({
        ...,
        beforeSend: (event, context) => {
            // RUM リソースの応答ヘッダーを収集します
            if (event.type === 'resource' && event.resource.type === 'fetch') {
                event.context = {...event.context, responseHeaders: context.response.headers}
            }
        },
        ...
    })
})

window.DD_RUM &&
    window.DD_RUM.init({
        ...,
        beforeSend: (event, context) => {
            // RUM リソースの応答ヘッダーを収集します
            if (event.type === 'resource' && event.resource.type === 'fetch') {
                event.context = {...event.context, responseHeaders: context.response.headers}
            }
        },
        ...
    });

ユーザーが複数のチームに所属している場合は、グローバルコンテキスト API を呼び出す際に、Key-Value ペアを追加してください。

RUM ブラウザ SDK は以下を無視します。

event.context の外に追加された属性
RUM ビューイベントコンテキストに加えられた変更

RUM イベントのコンテンツを変更

たとえば、Web アプリケーションの URL からメールアドレスを編集するには

import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    ...,
    beforeSend: (event) => {
        // ビューの URL からメールを削除します
        event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED")
    },
    ...
});

DD_RUM.onReady(function() {
    DD_RUM.init({
        ...,
        beforeSend: (event) => {
            // ビューの URL からメールを削除します
            event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED")
        },
        ...
    })
})

window.DD_RUM &&
    window.DD_RUM.init({
        ...,
        beforeSend: (event) => {
            // ビューの URL からメールを削除します
            event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED")
        },
        ...
    });

次のイベントプロパティを更新できます。

属性	タイプ	説明
`view.url`	文字列	アクティブな Web ページの URL。
`view.referrer`	文字列	現在リクエストされているページへのリンクがたどられた前のウェブページの URL。
`action.target.name`	文字列	ユーザーが操作した要素。自動的に収集されたアクションの場合のみ。
`error.message`	文字列	エラーについて簡潔にわかりやすく説明する 1 行メッセージ。
`error.stack`	文字列	スタックトレースまたはエラーに関する補足情報。
`error.resource.url`	文字列	エラーをトリガーしたリソース URL。
`resource.url`	文字列	リソースの URL。
`context`	オブジェクト	グローバルコンテキスト API を使って、またはイベントを手動で生成するときに追加される属性 (例: `addError` および `addAction`)。RUM ビューイベント `context` は読み取り専用です。

RUM ブラウザ SDK は、上記にリストされていないイベントプロパティに加えられた変更を無視します。イベントプロパティの詳細については、RUM ブラウザ SDK GitHub リポジトリを参照してください。

RUM イベントを破棄

beforeSend API で、false を返し RUM イベントを破棄します。

import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    ...,
    beforeSend: (event) => {
        if (shouldDiscard(event)) {
            return false
        }
        ...
    },
    ...
});

DD_RUM.onReady(function() {
    DD_RUM.init({
        ...,
        beforeSend: (event) => {
            if (shouldDiscard(event)) {
                return false
            },
            ...
        },
        ...
    })
})

window.DD_RUM &&
    window.DD_RUM.init({
        ...,
        beforeSend: (event) => {
            if (shouldDiscard(event)) {
                return false
            }
            ...
        },
        ...
    });

ユーザーセッション

RUM セッションにユーザー情報を追加すると、次の役に立ちます。

特定のユーザーのジャーニーをたどる
エラーの影響を最も受けているユーザーを把握する
最も重要なユーザーのパフォーマンスを監視する

次の属性はオプションですが、Datadog は少なくとも 1 つを指定することを推奨しています。

属性	タイプ	説明
`usr.id`	文字列	一意のユーザー識別子。
`usr.name`	文字列	RUM UI にデフォルトで表示されるユーザーフレンドリーな名前。
`usr.email`	文字列	ユーザー名が存在しない場合に RUM UI に表示されるユーザーのメール。Gravatar をフェッチするためにも使用されます。

推奨される属性に加えてさらに属性を追加することで、フィルタリング機能を向上できます。たとえば、ユーザープランに関する情報や、所属するユーザーグループなどを追加します。

ユーザーセッションオブジェクトに変更を加えた場合、変更後に収集されるすべての RUM イベントには、更新された情報が含まれます。

ユーザーセッションを特定する

datadogRum.setUser(<USER_CONFIG_OBJECT>)

datadogRum.setUser({
    id: '1234',
    name: 'John Doe',
    email: 'john@doe.com',
    plan: 'premium',
    ...
})

DD_RUM.onReady(function() {
    DD_RUM.setUser({
        id: '1234',
        name: 'John Doe',
        email: 'john@doe.com',
        plan: 'premium',
        ...
    })
})

window.DD_RUM && window.DD_RUM.setUser({
    id: '1234',
    name: 'John Doe',
    email: 'john@doe.com',
    plan: 'premium',
    ...
})

ユーザーセッションにアクセスする

datadogRum.getUser()

datadogRum.getUser()

DD_RUM.onReady(function() {
    DD_RUM.getUser()
})

window.DD_RUM && window.DD_RUM.getUser()

ユーザーセッションプロパティの追加/オーバーライド

datadogRum.setUserProperty('<USER_KEY>', <USER_VALUE>)

datadogRum.setUserProperty('name', 'John Doe')

DD_RUM.onReady(function() {
    DD_RUM.setUserProperty('name', 'John Doe')
})

window.DD_RUM && window.DD_RUM.setUserProperty('name', 'John Doe')

ユーザーセッションプロパティを削除する

datadogRum.removeUserProperty('<USER_KEY>')

datadogRum.removeUserProperty('name')

DD_RUM.onReady(function() {
    DD_RUM.removeUserProperty('name')
})

window.DD_RUM && window.DD_RUM.removeUserProperty('name')

ユーザーセッションプロパティをクリアする

datadogRum.clearUser()

RUM ブラウザ SDK v4.17.0 で `clearUser` が導入され、`removeUser` が廃止されました。

datadogRum.clearUser()

DD_RUM.onReady(function() {
    DD_RUM.clearUser()
})

window.DD_RUM && window.DD_RUM.clearUser()

サンプリング

デフォルトでは、収集セッション数にサンプリングは適用されていません。収集セッション数に相対サンプリング (% 表示) を適用するには、RUM を初期化する際に sessionSampleRate パラメーターを使用します。

下記の例では、RUM アプリケーションの全セッションの 90% のみを収集します。

import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    applicationId: '<DATADOG_APPLICATION_ID>',
    clientToken: '<DATADOG_CLIENT_TOKEN>',
    site: '<DATADOG_SITE>',
    sessionSampleRate: 90,
});

<script>
 (function(h,o,u,n,d) {
   h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
   d=o.createElement(u);d.async=1;d.src=n
   n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
})(window,document,'script','https://www.datadoghq-browser-agent.com/datadog-rum-v4.js','DD_RUM')
  DD_RUM.onReady(function() {
    DD_RUM.init({
        clientToken: '<CLIENT_TOKEN>',
        applicationId: '<APPLICATION_ID>',
        site: '<DATADOG_SITE>',
        sessionSampleRate: 90,
    })
  })
</script>

window.DD_RUM &&
    window.DD_RUM.init({
        clientToken: '<CLIENT_TOKEN>',
        applicationId: '<APPLICATION_ID>',
        site: '<DATADOG_SITE>',
        sessionSampleRate: 90,
    });

サンプルとして抽出したセッションでは、すべてのページビューとそのセッションに紐付くテレメトリーは収集されません。

グローバルコンテキスト

グローバルコンテキストプロパティを追加する

RUM を初期化した後、setGlobalContextProperty(key: string, value: any) API を使用してアプリケーションから収集したすべての RUM イベントにコンテキストを追加します。

RUM ブラウザ SDK v4.17.0 で `setGlobalContextProperty` が導入され、`addRumGlobalContext` が廃止されました。

import { datadogRum } from '@datadog/browser-rum';

datadogRum.setGlobalContextProperty('<CONTEXT_KEY>', <CONTEXT_VALUE>);

// コード例
datadogRum.setGlobalContextProperty('activity', {
    hasPaid: true,
    amount: 23.42
});

DD_RUM.onReady(function() {
    DD_RUM.setGlobalContextProperty('<CONTEXT_KEY>', '<CONTEXT_VALUE>');
})

// コード例
DD_RUM.onReady(function() {
    DD_RUM.setGlobalContextProperty('activity', {
        hasPaid: true,
        amount: 23.42
    });
})

window.DD_RUM && window.DD_RUM.setGlobalContextProperty('<CONTEXT_KEY>', '<CONTEXT_VALUE>');

// コード例
window.DD_RUM && window.DD_RUM.setGlobalContextProperty('activity', {
    hasPaid: true,
    amount: 23.42
});