Modifying RUM Data and Context

Overview

There are various ways you can modify the data collected by RUM, to support your needs for:

Protecting sensitive data like personally identifiable information.
Connecting a user session with your internal identification of that user, to help with support.
Reducing how much RUM data you’re collecting, through sampling the data.
Providing more context than what the default attributes provide about where the data is coming from.

Override default RUM view names

The RUM Browser SDK automatically generates a view event for each new page visited by your users, or when the page URL is changed (for single-page applications). A view name is computed from the current page URL, where variable alphanumeric IDs are removed automatically. For example, /dashboard/1234 becomes /dashboard/?.

Starting with version 2.17.0, you can add view names and assign them to a dedicated service owned by a team by tracking view events manually with the trackViewsManually option:

Set trackViewsManually to true when initializing the RUM Browser SDK.

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

You must start views for each new page or route change (for single-page applications). RUM data is collected when the view starts. Optionally, define the associated view name, service name, and version.
- View: Defaults to the page URL path.
- Service: Defaults to the default service specified when creating your RUM application.
- Version: Defaults to the default version specified when creating your RUM application.
For more information, see Setup Browser Monitoring.

The following example manually tracks the page views on the checkout page in a RUM application. Use checkout for the view name and associate the purchase service with version 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'
})

If you are using React, Angular, Vue, or any other frontend framework, Datadog recommends implementing the startView logic at the framework router level.

Enrich and control RUM data

The RUM Browser SDK captures RUM events and populates their main attributes. The beforeSend callback function gives you access to every event collected by the RUM Browser SDK before it is sent to Datadog.

Intercepting the RUM events allows you to:

Enrich your RUM events with additional context attributes
Modify your RUM events to alter their content or redact sensitive sequences (see list of editable properties)
Discard selected RUM events

Starting with version 2.13.0, beforeSend takes two arguments: the event generated by the RUM Browser SDK, and the context that triggered the creation of the RUM event.

function beforeSend(event, context)

The potential context values are:

RUM event type	Context
View	Location
Action	Event
Resource (XHR)	XMLHttpRequest and PerformanceResourceTiming
Resource (Fetch)	Request, Response, and PerformanceResourceTiming
Resource (Other)	PerformanceResourceTiming
Error	Error
Long Task	PerformanceLongTaskTiming

For more information, see the Enrich and control RUM data guide.

Enrich RUM events

Along with attributes added with the Global Context API, you can add additional context attributes to the event. For example, tag your RUM resource events with data extracted from a fetch response object:

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

datadogRum.init({
    ...,
    beforeSend: (event, context) => {
        // collect a RUM resource's response headers
        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) => {
            // collect a RUM resource's response headers
            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) => {
            // collect a RUM resource's response headers
            if (event.type === 'resource' && event.resource.type === 'fetch') {
                event.context = {...event.context, responseHeaders: context.response.headers}
            }
        },
        ...
    });

If a user belongs to multiple teams, add additional key-value pairs in your calls to the Global Context API.

The RUM Browser SDK ignores:

Attributes added outside of event.context
Modifications made to a RUM view event context

Modify the content of a RUM event

For example, to 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:

Attribute	Type	Description
`view.url`	String	The URL of the active web page.
`view.referrer`	String	The URL of the previous web page from which a link to the currently requested page was followed.
`action.target.name`	String	The element that the user interacted with. Only for automatically collected actions.
`error.message`	String	A concise, human-readable, one-line message explaining the error.
`error.stack`	String	The stack trace or complementary information about the error.
`error.resource.url`	String	The resource URL that triggered the error.
`resource.url`	String	The resource URL.
`context`	Object	Attributes added with the Global Context API or when generating events manually (for example, `addError` and `addAction`). RUM view events `context` is read-only.

The RUM Browser SDK ignores modifications made to event properties not listed above. For more information about event properties, see the RUM Browser SDK GitHub repository.

Discard a RUM event

With the beforeSend API, discard a RUM event by returning false:

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

User session

Adding user information to your RUM sessions can help you:

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 Datadog recommends providing at least one of them:

Attribute	Type	Description
`usr.id`	String	Unique user identifier.
`usr.name`	String	User friendly name, displayed by default in the RUM UI.
`usr.email`	String	User email, displayed in the RUM UI if the user name is not present. It is also used to fetch Gravatars.

Increase your filtering capabilities by adding extra attributes on top of the recommended ones. For instance, add information about the user plan, or which user group they belong to.

When making changes to the user session object, all RUM events collected after the change contain the updated information.

Identify user session

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

Access user session

datadogRum.getUser()

datadogRum.getUser()

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

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

Add/Override user session property

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')

Remove user session property

datadogRum.removeUserProperty('<USER_KEY>')

datadogRum.removeUserProperty('name')

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

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

Clear user session property

datadogRum.clearUser()

The RUM Browser SDK v4.17.0 introduced `clearUser` and deprecated `removeUser`

datadogRum.clearUser()

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

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

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

For a sampled out session, all page views and associated telemetry for that session are not collected.

Global context

Add global context property

After RUM is initialized, add extra context to all RUM events collected from your application with the setGlobalContextProperty(key: string, value: any) API:

The RUM Browser SDK v4.17.0 introduced `setGlobalContextProperty` and deprecated `addRumGlobalContext`

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

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

// Code example
datadogRum.setGlobalContextProperty('activity', {
    hasPaid: true,
    amount: 23.42
});

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

// Code example
DD_RUM.onReady(function() {
    DD_RUM.setGlobalContextProperty('activity', {
        hasPaid: true,
        amount: 23.42
    });
})

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

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

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

Remove global context property

You can remove a previously defined global context property.

The RUM Browser SDK v4.17.0 introduced `removeGlobalContextProperty` and deprecated `removeRumGlobalContext`

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

Replace global context

Replace the default context for all your RUM events with the setGlobalContext(context: Context) API:

The RUM Browser SDK v4.17.0 introduced `setGlobalContext` and deprecated `setRumGlobalContext`

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

Clear global context

You can clear the global context by using clearGlobalContext.

Read global context

Once RUM is initialized, read the global context with the getGlobalContext() API:

The RUM Browser SDK v4.17.0 introduced `getGlobalContext` and deprecated `getRumGlobalContext`

Modifying RUM Data and Context

Overview

Override default RUM view names

Enrich and control RUM data

Enrich RUM events

Modify the content of a RUM event

Discard a RUM event

User session

Identify user session

Access user session

Add/Override user session property

Remove user session property

Clear user session property

Sampling

Global context

Add global context property

Remove global context property

Replace global context

Clear global context

Read global context

Further Reading