RUM Advanced Configuration
Incident Management is now generally available! Incident Management is now generally available!

RUM Advanced Configuration

Initialization

Find below the different initialization options available with the Datadog Browser SDK.

Scrub sensitive data from your RUM data

If your RUM data contains sensitive information that need redacting, configure the Browser SDK to scrub sensitive sequences by using the beforeSend callback when you initialize RUM.

This callback function gives you access to every event collected by the RUM SDK before they get sent to Datadog.

For example, redact email addresses from your web application URLs:

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

datadogRum.init({
    ...,
    beforeSend: (event) => {
        // remove email from view url
        event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED")
    },
    ...
});
DD_RUM.onReady(function() {
    DD_RUM.init({
        ...,
        beforeSend: (event) => {
            // remove email from view url
            event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED")
        },
        ...
    })
})
window.DD_RUM &&
    window.DD_RUM.init({
        ...,
        beforeSend: (event) => {
            // remove email from view url
            event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED")
        },
        ...
    });

You can update the following event properties:

AttributeTypeDescription
view.urlStringThe URL of the active web page.
view.referrerStringThe URL of the previous web page from which a link to the currently requested page was followed.
action.target.nameStringThe element that the user interacted with. Only for automatically collected actions.
error.messageStringA concise, human-readable, one-line message explaining the error.
error.stackStringThe stack trace or complementary information about the error.
error.resource.urlStringThe resource URL that triggered the error.
resource.urlStringThe resource URL.

Note: The RUM SDK will ignore modifications made to event properties not listed above. Find out about all event properties on the Browser SDK repository.

Identify user sessions

Adding user information to your RUM sessions makes it easy to:

  • Follow the journey of a given user
  • Know which users are the most impacted by errors
  • Monitor performance for your most important users

The following attributes are optional but it is recommended to provide at least one of them:

AttributeTypeDescription
usr.idStringUnique user identifier.
usr.nameStringUser friendly name, displayed by default in the RUM UI.
usr.emailStringUser email, displayed in the RUM UI if the user name is not present. It is also used to fetch Gravatars.

To identify user sessions, use the setUser API:

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

Sampling

By default, no sampling is applied on the number of collected sessions. To apply a relative sampling (in percent) to the number of sessions collected, use the sampleRate parameter when initializing RUM. The following example collects only 90% of all sessions on a given RUM application:

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,
    });

Note: For a sampled out session, all page views and associated telemetry for that session aren’t collected.

API available

Add global context

Once Real User Monitoring (RUM) is initialized, add extra context to all RUM events collected from your application with the addRumGlobalContext(key: string, value: any) API:

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

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

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

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

// Code example
window.DD_RUM && window.DD_RUM.addRumGlobalContext('activity', {
    hasPaid: true,
    amount: 23.42
});

Note: Follow the Datadog naming convention for a better correlation of your data across the product.

Replace global context

Once Real User Monitoring (RUM) is initialized, replace the default context for all your RUM events with the setRumGlobalContext(context: Context) API:

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

datadogRum.setRumGlobalContext({ '<CONTEXT_KEY>': '<CONTEXT_VALUE>' });

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

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

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

Note: Follow the Datadog naming convention for a better correlation of your data across the product.

Read global context

Once Real User Monitoring (RUM) is initialized, read the global context with the 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();

Further Reading