@datadog/browser-rum
    TypeScript icon, indicating that this package has built-in type declarations

    4.13.0 • Public • Published

    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

    The RUM Browser SDK supports all modern desktop and mobile browsers including IE11. For more information, see the Browser Support table.

    To set up RUM Browser Monitoring:

    1. In Datadog, navigate to the RUM Applications 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 RUM Browser SDK with npm or a hosted version (CDN async or CDN sync).
    4. Deploy the changes to your application. Once your deployment is live, Datadog collects events from your users' browsers.
    5. Visualize the data collected in dashboards or create a search query in the RUM Explorer.

    Until Datadog starts to receive data, your application appears as "pending" on the RUM Applications page.

    Choose the right installation method

    npm (node package manager) : This method is recommended for modern web applications. The RUM Browser SDK is packaged with the rest of your front-end JavaScript code. It has no impact on page load performance. However, the SDK may miss errors, resources, and user actions triggered before the SDK is initialized. Datadog recommends using a matching version with the Browser Logs SDK if you are collecting logs.

    CDN async : This method is recommended for web applications with performance targets. The RUM Browser SDK loads from our CDN asynchronously, ensuring the SDK download does not impact page load performance. However, the SDK may 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 Browser SDK loads from our CDN synchronously, ensuring the SDK loads first and collects all errors, resources, and user actions. This method may 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,
      premiumSampleRate: 100, // if not included - default 100
      trackInteractions: true,
    })

    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,
          premiumSampleRate: 100, // if not included - default 100
          trackInteractions: true,
        })
      })
    </script>

    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,
          premiumSampleRate: 100, // if not included - default 100
          trackInteractions: true,
        })
    </script>

    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 Browser 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, the same value as the Agent site configuration.

    service : Optional
    Type: String
    The service name for your application. Follows the tag syntax requirements.

    env : Optional
    Type: String
    The application’s environment, for example: prod, pre-prod, and staging. Follows the tag syntax requirements.

    version : Optional
    Type: String
    The application’s version, for example: 1.2.3, 6c44da20, and 2020.02.13. Follows 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 - Deprecated
    Type: Number
    Default: 100
    See premiumSampleRate.

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

    silentMultipleInit : Optional
    Type: Boolean
    Default: false
    Initialization fails silently if the RUM Browser SDK is already initialized on the page.

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

    allowedTracingOrigins : Optional
    Type: List
    A list of request origins used to inject tracing headers. For more information, see Connect RUM and Traces.

    tracingSampleRate : Optional
    Type: Number
    Default: 100
    The percentage of requests to trace: 100 for all, 0 for none. For more information, 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.

    excludedActivityUrls : Optional
    Type: List
    A list of request origins ignored when computing the page activity. See How page activity is calculated.

    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 Browser 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 RUM and RUM Premium sampling configuration

    This feature requires the RUM Browser SDK v3.6.0+.

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

    • Browser RUM: Only Sessions, Views, Actions, and Errors are collected. Calls to startSessionReplayRecording() are ignored.
    • RUM Premium: Everything from Browser RUM, including Resources, Long Tasks, and Replay recordings are collected. To collect Replay recordings, call startSessionReplayRecording().

    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 is tracked by default.
    • premiumSampleRate is applied after the overall sample rate, and controls the percentage of sessions tracked as RUM Premium. It defaults to 100%, so every sessions is tracked as RUM Premium by default.

    To track 100% of your sessions as Browser RUM:

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

    To track 100% of your sessions as RUM Premium:

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

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

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

    Further Reading

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

    Keywords

    none

    Install

    npm i @datadog/browser-rum

    DownloadsWeekly Downloads

    902,784

    Version

    4.13.0

    License

    Apache-2.0

    Unpacked Size

    1.37 MB

    Total Files

    219

    Last publish

    Collaborators

    • datadog