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

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

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

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

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

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

バージョン 2.17.0 以降、trackViewsManually オプションを使用してビューイベントを手動で追跡することにより、独自のビュー名を指定できます。

  1. RUM を初期化するときに 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,
            ...
        });
    

  2. 新しいページまたはルートの変更ごとにビューを開始する必要があります (シングルページアプリケーションの場合)。オプションで、関連付けられたビュー名を定義できます。デフォルトでは、ページの URL パスになります。ビューが開始されるまで、RUM データは収集されません。

    datadogRum.startView('checkout')
    
    DD_RUM.onReady(function() {
        DD_RUM.startView('checkout')
    })
    
    window.DD_RUM && window.DD_RUM.startView('checkout')
    

: 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)XMLHttpRequestPerformanceResourceTiming
リソース (フェッチ)リクエストリソースPerformanceResourceTiming
リソース (その他)PerformanceResourceTiming
エラーエラー
ロングタスク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}
            }
        },
        ...
    });

: 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 は、上記にリストされていないイベントプロパティに加えられた変更を無視します。すべてのイベントプロパティについては、Browser SDK リポジトリを参照してください。

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 セッションにユーザー情報を追加すると、次のことが簡単になります。

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

次の属性はオプションですが、少なくとも 1 つを指定することをお勧めします。

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

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

ユーザーセッションを識別するには、setUser API を使用します。

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',
    ...
})

ユーザー ID を削除

removeUser API で、以前に設定されたユーザーを消去します。この後に収集されたすべての RUM イベントにユーザー情報は含まれません。

datadogRum.removeUser()
DD_RUM.onReady(function() {
    DD_RUM.removeUser()
})
window.DD_RUM && window.DD_RUM.removeUser()

サンプリング

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

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

datadogRum.init({
    applicationId: '<DATADOG_APPLICATION_ID>',
    clientToken: '<DATADOG_CLIENT_TOKEN>',
    site: '<DATADOG_SITE>',
    sampleRate: 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.js','DD_RUM')
  DD_RUM.onReady(function() {
    DD_RUM.init({
        clientToken: '<CLIENT_TOKEN>',
        applicationId: '<APPLICATION_ID>',
        site: '<DATADOG_SITE>',
        sampleRate: 90,
    })
  })
</script>
window.DD_RUM &&
    window.DD_RUM.init({
        clientToken: '<CLIENT_TOKEN>',
        applicationId: '<APPLICATION_ID>',
        site: '<DATADOG_SITE>',
        sampleRate: 90,
    });

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

グローバルコンテキスト

グローバルコンテキストを追加

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

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

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

// コード例
datadogRum.addRumGlobalContext('activity', {
    hasPaid: true,
    amount: 23.42
});
DD_RUM.onReady(function() {
    DD_RUM.addRumGlobalContext('<CONTEXT_KEY>', '<CONTEXT_VALUE>');
})

// コード例
DD_RUM.onReady(function() {
    DD_RUM.addRumGlobalContext('activity', {
        hasPaid: true,
        amount: 23.42
    });
})
window.DD_RUM && window.DD_RUM.addRumGlobalContext('<CONTEXT_KEY>', '<CONTEXT_VALUE>');

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

: 製品全体でデータの相関を高めるには Datadog の命名規則に従ってください。

グローバルコンテキストを置換

RUM を初期化したら、setRumGlobalContext(context: Context) API を使用してすべての RUM イベントのデフォルトコンテキストを置換します。

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

datadogRum.setRumGlobalContext({ '<コンテキストキー>', <コンテキスト値>' });

// Code example
datadogRum.setRumGlobalContext({
    codeVersion: 34,
});
DD_RUM.onReady(function() {
    DD_RUM.setRumGlobalContext({ '<CONTEXT_KEY>': '<CONTEXT_VALUE>' });
})

// コード例
DD_RUM.onReady(function() {
    DD_RUM.setRumGlobalContext({
        codeVersion: 34,
    })
})
window.DD_RUM &&
    DD_RUM.setRumGlobalContext({ '<コンテキストキー>', <コンテキスト値>' });

// Code example
window.DD_RUM &&
    DD_RUM.setRumGlobalContext({
        codeVersion: 34,
    });

: 製品全体でデータの相関を高めるには Datadog の命名規則に従ってください。

グローバルコンテキストを読み取る

RUM を初期化したら、getRumGlobalContext() API を使用してグローバルコンテキストを読み取ります。

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

const context = datadogRum.getRumGlobalContext();
DD_RUM.onReady(function() {
  var context = DD_RUM.getRumGlobalContext();
});
var context = window.DD_RUM && DD_RUM.getRumGlobalContext();

その他の参考資料