Modifying RUM Data and Context
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 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 may specify your own view names by tracking view events manually with the trackViewsManually
option:
Set trackViewsManually
to true when initializing RUM.
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). You can optionally define the associated view name, which defaults to the page URL path. No RUM data is collected until the view is started.
datadogRum.startView('checkout')
DD_RUM.onReady(function() {
DD_RUM.startView('checkout')
})
window.DD_RUM && window.DD_RUM.startView('checkout')
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:
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 via 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
}
...
},
...
});
Identify user sessions
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 it is recommended to provide 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.
To identify user sessions, use the 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',
...
})
Remove the user identification
Clear a previously set user with the removeUser
API. All RUM events collected afterwards do not contain user information.
DD_RUM.onReady(function() {
DD_RUM.removeUser()
})
window.DD_RUM && window.DD_RUM.removeUser()
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-v4.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,
});
For a sampled out session, all page views and associated telemetry for that session are not collected.
Global context
Add global context
Once 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
});
Follow the Datadog naming convention for a better correlation of your data across the product.
Replace global context
Once 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,
});
Follow the Datadog naming convention for a better correlation of your data across the product.
Read global context
Once 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
Additional helpful documentation, links, and articles: