RUM Browser Monitoring

Overview

Datadog Real User Monitoring (RUM) enables you to visualize and analyze the real-time performance and user journeys of your application's individual users.

Setup

To set up Datadog RUM browser monitoring:

1. In Datadog, navigate to the Real User Monitoring page and click the New Application button.
2. Enter a name for your application and click Generate Client Token. This generates a clientToken and an applicationId for your application.
3. Setup the Datadog RUM SDK via npm or via one of the hosted versions: CDN async or CDN sync.
4. Deploy the changes to your application. Once your deployment is live, Datadog collects events from user browsers.
5. Visualize the data collected using Datadog dashboards.

Note: Your application shows up on the application list page as "pending" until Datadog starts receiving data.

Supported browsers: The RUM SDK supports all modern desktop and mobile browsers including IE11. See the browser support table.

Choose the right installation method

npm (node package manager) : This method is recommended for modern web applications. The RUM SDK gets packaged with the rest of your front-end javascript code. It has no impact on page load performance. However, the SDK might miss errors, resources and user actions triggered before the SDK is initialized. Note: it is recommended to use a matching version with logs SDK if used.

CDN async : This method is recommended for web applications with performance targets. The RUM SDK is loaded from our CDN asynchronously: this method ensures the SDK download does not impact page load performance. However, the SDK might miss errors, resources and user actions triggered before the SDK is initialized.

CDN sync : This method is recommended for collecting all RUM events. The RUM SDK is loaded from our CDN synchronously: this method ensures the SDK is loaded first and collects all errors, resources and user actions. This method might impact page load performance.

npm

Add @datadog/browser-rum to your package.json file, then initialize it with:

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

datadogRum.init({
  applicationId: '<DATADOG_APPLICATION_ID>',
  clientToken: '<DATADOG_CLIENT_TOKEN>',
  site: '<DATADOG_SITE>',
  //  service: 'my-web-application',
  //  env: 'production',
  //  version: '1.0.0',
  sampleRate: 100,
  replaySampleRate: 100, // if not included - default 100
  trackInteractions: true,
})

Note: The trackInteractions parameter enables the automatic collection of user clicks in your application. Sensitive and private data contained on your pages may be included to identify the elements interacted with.

CDN async

Add the generated code snippet to the head tag of every HTML page you want to monitor in your application.

<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>',
      //  service: 'my-web-application',
      //  env: 'production',
      //  version: '1.0.0',
      sampleRate: 100,
      replaySampleRate: 100, // if not included - default 100
      trackInteractions: true,
    })
  })
</script>

Notes:

• The trackInteractions parameter enables the automatic collection of user clicks in your application. Sensitive and private data contained on your pages may be included to identify the elements interacted with.
• Early RUM API calls must be wrapped in the DD_RUM.onReady() callback. This ensures the code only gets executed once the SDK is properly loaded.

CDN sync

Add the generated code snippet to the head tag (in front of any other script tags) of every HTML page you want to monitor in your application. Including the script tag higher and synchronized ensures Datadog RUM can collect all performance data and errors.

<script src="https://www.datadoghq-browser-agent.com/datadog-rum-v4.js" type="text/javascript"></script>
<script>
  window.DD_RUM &&
    window.DD_RUM.init({
      clientToken: '<CLIENT_TOKEN>',
      applicationId: '<APPLICATION_ID>',
      site: '<DATADOG_SITE>',
      //  service: 'my-web-application',
      //  env: 'production',
      //  version: '1.0.0',
      sampleRate: 100,
      replaySampleRate: 100, // if not included - default 100
      trackInteractions: true,
    })
</script>

Notes:

• The trackInteractions parameter enables the automatic collection of user clicks in your application. Sensitive and private data contained on your pages may be included to identify the elements interacted with.
• The window.DD_RUM check is used to prevent issues if a loading failure occurs with the RUM SDK.

TypeScript

Types are compatible with TypeScript >= 3.8.2. For earlier versions, import JS sources and use global variables to avoid any compilation issues:

import '@datadog/browser-rum/bundle/datadog-rum'

window.DD_RUM.init({
  applicationId: 'XXX',
  clientToken: 'XXX',
  site: 'datadoghq.com',
  sampleRate: 100,
})

Configuration

Initialization parameters

The following parameters are available:

applicationId : Required
Type: String
The RUM application ID.

clientToken : Required
Type: String
A Datadog client token.

site : Required
Type: String
Default: datadoghq.com
The Datadog site of your organization, same value as agent site configuration.

service : Optional
Type: String
The service name for your application. It should follow the tag syntax requirements.

env : Optional
Type: String
The application’s environment, for example: prod, pre-prod, staging, etc. It should follow the tag syntax requirements.

version : Optional
Type: String
The application’s version, for example: 1.2.3, 6c44da20, 2020.02.13, etc. It should follow the tag syntax requirements.

trackViewsManually : Optional
Type: Boolean
Default: false
Allows you to control RUM views creation. See override default RUM view names.

trackInteractions : Optional
Type: Boolean
Default: false
Enables automatic collection of users actions.

defaultPrivacyLevel : Optional
Type: String
Default: mask-user-input
See Session Replay Privacy Options.

actionNameAttribute : Optional
Type: String
Specify your own attribute to be used to name actions.

sampleRate : Optional
Type: Number
Default: 100
The percentage of sessions to track: 100 for all, 0 for none. Only tracked sessions send RUM events. For more details about sampleRate, see the sampling configuration.

replaySampleRate : Optional
Type: Number
Default: 100
The percentage of tracked sessions with Session Replay pricing features: 100 for all, 0 for none. For more details about replaySampleRate, see the sampling configuration.

silentMultipleInit : Optional
Type: Boolean
Default: false
Initialization fails silently if Datadog's RUM is already initialized on the page.

proxyUrl : Optional
Type: String
Optional proxy URL (ex: https://www.proxy.com/path), see the full proxy setup guide for more information.

allowedTracingOrigins : Optional
Type: List
A list of request origins used to inject tracing headers. See Connect RUM and Traces.

tracingSampleRate : Optional
Type: Number
Default: 100
The percentage of requests to trace: 100 for all, 0 for none. See Connect RUM and Traces.

telemetrySampleRate : Optional
Type: Number
Default: 20
Telemetry data (error, debug logs) about SDK execution is sent to Datadog in order to detect and solve potential issues. Set this option to 0 to opt out from telemetry collection.

Options that must have matching configuration when also using logs SDK:

trackSessionAcrossSubdomains : Optional
Type: Boolean
Default: false
Preserve the session across subdomains for the same site.

useSecureSessionCookie : Optional
Type: Boolean
Default: false
Use a secure session cookie. This disables RUM events sent on insecure (non-HTTPS) connections.

useCrossSiteSessionCookie : Optional
Type: Boolean
Default:false
Use a secure cross-site session cookie. This allows the RUM SDK to run when the site is loaded from another one (iframe). Implies useSecureSessionCookie.

Example

Init must be called to start the tracking:

init(configuration: {
    applicationId: string,
    clientToken: string,
    site?: string,
    sampleRate?: number,
    silentMultipleInit?: boolean,
    trackInteractions?: boolean,
    service?: string,
    env?: string,
    version?: string,
    allowedTracingOrigins?: Array<String|Regexp>,
    trackSessionAcrossSubdomains?: boolean,
    useSecureSessionCookie?: boolean,
    useCrossSiteSessionCookie?: boolean,
})

Browser and Session Replay sampling configuration

Note: This feature requires SDK v3.6.0+.

When new session is created, it can be either tracked as:

• Browser RUM: Only Sessions, Views, Actions, and Errors are collected. Calls to startSessionReplayRecording() are ignored.
• Session Replay RUM: Everything from Browser RUM plus Resources, Long Tasks, and Replay recordings are collected. A call to startSessionReplayRecording() is needed to collect Replay recordings.

Two initialization parameters are available to control how the session is tracked:

• sampleRate controls the percentage of overall sessions being tracked. It defaults to 100%, so every sessions will be tracked by default.

• replaySampleRate is applied after the overall sample rate, and controls the percentage of sessions tracked as Session Replay RUM. It defaults to 100%, so every sessions will be tracked as Session Replay RUM by default.

For example, to track 100% of your sessions as Browser RUM:

datadogRum.init({
    ....
    sampleRate: 100,
    replaySampleRate: 0
});

For example, to track 100% of your sessions as Session Replay RUM:

datadogRum.init({
    ....
    sampleRate: 100,
    replaySampleRate: 100
});

For example, to track only 50% of your overall sessions, with half tracked as Browser RUM and the other half tracked as Session Replay RUM, set the sampleRate and the replaySampleRate to 50:

datadogRum.init({
    ....
    sampleRate: 50,
    replaySampleRate: 50
});

Further Reading

{{< partial name="whats-next/whats-next.html" >}}