Initialization method

To configure the Splunk RUM browser agent, edit the object passed to the SplunkRum.init() function:

<script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
<script>
      SplunkRum.init(
      {
         applicationName: 'my-awesome-app',
         realm: 'us0',
         rumAccessToken: 'ABC123...789',
         version: '1.0.1'
         // Any additional general settings
      });
</script>

General settings

To configure the Splunk RUM browser agent, use the following properties in SplunkRum.init():

context.async

Traces that happen asynchronously, such as user interactions that result in a promise chain, might get disconnected from parent activity. To avoid this problem, the Splunk RUM browser agent includes a custom context manager that connects parent traces with traces that happen when using the following properties or patterns:

• setTimeout with less than 34ms timeout

• setImmediate

• requestAnimationFrame

• Promise.then / catch / finally

• MutationObserver on textNode

• MessagePort

• Hash-based routers

Asynchronous trace linking is activated by default. In case of compatibility issues you can deactivate it by setting the context.async property to false.

The context manager allows Splunk RUM to link requests executed when a component is first rendered to the user interaction that caused the application to add the component to the page. XMLHttpRequest events and Fetch API events through promise methods are patched to preserve the parent context, so subsequent requests link to their parents.

The following limitations apply when using asynchronous tracing:

• async/await functions aren’t supported. Down-compile the code using Babel and targeting older browsers.

  document.getElementById('save-button').addEventListener('click', async () => {
    const saveRes = await fetch('/api/items', {method: 'POST'});
  
    const listRes = await fetch('/api/items'); // Can be disconnected from click event when not transpiled
  });

• Only code loaded by promise-based implementations is linked to the parent interaction.

cookieDomain

The Splunk RUM browser agent uses the following cookies to link traces to sessions:

globalAttributes

Valid values:

instrumentations

To activate, deactivate, or configure Splunk RUM browser instrumentation modules, compose an instrumentations object and include it in your SplunkRum.init() function call. For example:

SplunkRum.init(
   {
      beaconEndpoint: 'https://rum-ingest.us0.signalfx.com/v1/rum',
      rumAccessToken: 'ABC123…789',
      applicationName: 'my-awesome-app',
      instrumentations:
      {
         interactions:
         {
            // Adds``gamepadconneted`` events to the
            // list of events collected by default
           eventNames: [
             ...SplunkRum.DEFAULT_AUTO_INSTRUMENTED_EVENT_NAMES,
             'gamepadconnected'
           ],
         },
         longtask: false, // Deactivates monitoring for longtasks
         websocket: true, // Activates monitoring for websockets
      },
   });

The following table describes the modules you can configure through the instrumentations object:

privacy

The Splunk RUM browser agent avoids capturing potentially private information by default. In other words, it records only the HTML node name by default. Use maskAllText and sensitivityRules for opt-in fine-grained click-text capture.

Precedence rules:

1. maskAllText is global unless overridden.

2. Rules are evaluated in order; specific overrides should come last.

3. exclude is absolute and cannot be overridden.

privacy.sensitivityRules

The sensitivityRules array gives you fine-grained control over what is recorded. You can mask, unmask, or exclude specific elements on the page from being recorded. Put general rules at the beginning of the array, and more specific rules at the end of the array.

Available rule types:

• mask: Replace the content of the element with black bars.

• unmask: Show the content of a masked element.

• exclude: Exclude the element from the recording. We do not record any interaction with this element;

Parameter	Type	Description
rule	string	Type of sensitivity. Valid values: 'mask', 'unmask', 'exclude'.
selector	string	CSS selector for sensitive elements. For example: p.sensitive selects all p elements with class="sensitive". ul ~ table selects all table elements that are siblings of a ul element.

Examples:

• Default safety (only node names recorded; zero privacy risk)

  {
    "maskAllText": true,
    "sensitivityRules": []
  }

• Selective unmask (all masked except safe product names)

  {
    "maskAllText": true,
    "sensitivityRules": [
      { "rule": "unmask", "selector": "p.product-name" }
    ]
  }

• Mixed (p masked except product labels; user profiles excluded completely)

  {
    "maskAllText": true,
    "sensitivityRules": [
      { "rule": "mask", "selector": "p" },
      { "rule": "unmask", "selector": "p.item-label" },
      { "rule": "exclude", "selector": "#user-profile" }
    ]
  }

• Unmasked by default, with specific mask (all text recorded except explicitly masked sensitive ones)

  {
    "maskAllText": false,
    "sensitivityRules": [
      { "rule": "mask", "selector": "p.sensitive" }
    ]
  }

tracer

By default, the Splunk RUM browser agent collects all of the data from all of the users. You can adjust sampling by passing a custom sampler to the tracer property.

The following example shows how to restrict sampling to logged in users:

CDN

<script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
<script>
   var shouldTrace = isUserLoggedIn();

   SplunkRum.init({
      realm: '<realm>',
      rumAccessToken: '<your_rum_token>',
      applicationName: '<application-name>',
      tracer: {
         sampler: shouldTrace ? new SplunkRum.AlwaysOnSampler() : new SplunkRum.AlwaysOffSampler(),
      },
   });
</script>

npm

// When using npm you can get samplers directly from @opentelemetry/core
import {AlwaysOnSampler, AlwaysOffSampler} from '@opentelemetry/core';
import SplunkOtelWeb from '@splunk/otel-web';

SplunkOtelWeb.init({
   beaconEndpoint: 'https://rum-ingest..signalfx.com/v1/rum',
   rumAccessToken: '<your_rum_token>',
   applicationName: '<application-name>',
   tracer: {
      sampler: userShouldBeTraced() ? new SplunkRum.AlwaysOnSampler() : new SplunkRum.AlwaysOffSampler(),
   },
});

The Splunk Distribution of OpenTelemetry JS for Web includes the following samplers:

Session-based sampler

The Splunk Distribution of OpenTelemetry JS for Web includes a custom sampler that supports sessions. Session ratios are preferable to trace ratios, as they keep data from each session intact.

You can access the session-based sampler in the following ways:

• Use the SplunkRum.SessionBasedSampler export when using the Splunk CDN build.

• Use the SessionBasedSampler export when using the npm package.

The session-based sampler accepts the following settings:

The following example shows how to collect RUM data from half of the sessions:

CDN

<script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
<script>
  SplunkRum.init({
    realm: '<realm>',
    rumAccessToken: '<your_rum_token>',
    applicationName: '<application-name>',
    tracer: {
      sampler: new SplunkRum.SessionBasedSampler({
      ratio: 0.5
      }),
    },
  });
</script>

npm

import SplunkOtelWeb, {SessionBasedSampler} from '@splunk/otel-web';

SplunkOtelWeb.init({
  realm: '<realm>',
  rumAccessToken: '<your_rum_token>',
  applicationName: '<application-name>',
  tracer: {
      sampler: new SessionBasedSampler({
        ratio: 0.5
      }),
  },
});

Context propagation settings

The Splunk RUM browser agent doesn’t register any context propagators, as it collects traceparent data from Server-Timing headers. If needed, you can register context propagators by using the OpenTelemetry API:

import {propagation} from '@opentelemetry/api';
import {B3Propagator} from '@opentelemetry/propagator-b3';

propagation.setGlobalPropagator(new B3Propagator());

When calling the OpenTelemetry API directly, make sure the API version you’re using matches the one used by the Splunk RUM browser agent.

Exporter settings

By default, the Splunk RUM browser agent uses the Zipkin exporter to send data to Splunk Observability Cloud.

Starting from version 0.17.0 and higher, you can configure the Splunk RUM browser agent to use the OTLP exporter. The following example shows how to configure the Splunk RUM browser to use the OTLP exporter:

   SplunkRum.init({
      realm: '<realm>',
      rumAccessToken: '<your_rum_token>',
      applicationName: '<application-name>',
      deploymentEnvironment: '<deployment-env>',
      exporter: {
         otlp: true
      },
   });

When setting the beaconEndpoint manually, use https://rum-ingest.<realm>.signalfx.com/v1/rumotlp as the OTLP endpoint. The endpoint is set automatically when exporter.otlp is true and a realm is configured.