Docs » Instrument mobile and web applications for Splunk RUM » Instrument browser-based web applications for Splunk RUM » Configure the Splunk Browser RUM instrumentation

Configure the Splunk Browser RUM instrumentation ๐Ÿ”—

You can configure the Browser RUM agent from the Splunk Distribution of OpenTelemetry JS for Web to add custom attributes, adapt the instrumentation to your environment and application, customize sampling, and more.

Configuration method ๐Ÿ”—

To configure the Browser RUM 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(
      {
         beaconUrl: 'https://rum-ingest.us0.signalfx.com/v1/rum'
         rumAuth: 'ABC123...789',
         app: 'my-awesome-app',
         version: '1.0.1'
         // Any additional settings
      });
</script>

General settings ๐Ÿ”—

Use the following settings to configure the Browser RUM agent:

Property

Type

Description

beaconUrl

String (required)

Ingest URL to which the agent sends collected telemetry. The URL must contain your realm in Splunk Observability Cloud. For example, https://rum-ingest.us0.signalfx.com/v1/rum is the ingest URL for the us0 realm.

rumAuth

String (required)

RUM token that authorizes the agent to send telemetry data to Splunk Observability Cloud. To generate a RUM access token, see Generate your RUM access token in Observability Cloud.

app

String

Name of the application. The default value is unknown-browser-app.

version

String

Version of the application for all spans. For example, โ€œ1.0.1โ€ or โ€œ20220820โ€.

environment

String

Environment for all the spans produced by the application. For example, dev, test, or prod.

globalAttributes

Object

Sets additional attributes added to all spans. For example, version or user_id.

instrumentations

Object

Enables or disables specific Browser RUM instrumentations. See Instrumentation settings.

ignoreUrls

(string\|regex)[]

List of URLs that the agent must ignore. Matching URLs donโ€™t produce spans. You can provide two different types of rules: strings or regular expressions.

cookieDomain

String

Domain used for session tracking. For example, if you have sites on both foo.example.com and bar.example.com, setting cookieDomain to example.com allows both sites to use the same session identifier. See Cookies used by the Browser RUM agent for more information.

context.async

Boolean

Enables the asynchronous context manager. The default value is false. See Asynchronous trace settings.

exporter.onAttributesSerializing

(a: SpanAttributes, s?: Span) => SpanAttributes

Provides a callback for modifying span attributes before theyโ€™re exported. The default value is (attrs) => attrs. A sample use case is Sanitize Personally Identifiable Information (PII).

tracer

Object

Tracing configuration passed to WebTracerProvider. You can use it to configure sampling. See Sampling settings.

debug

Boolean

Enables debug logging in the developer console. The default value is false.

Instrumentation settings ๐Ÿ”—

To enable or disable specific Browser RUM instrumentations, compose and pass an object to the instrumentations property. The following example of agent initialization changes the settings of several instrumentations:

SplunkRum.init(
   {
      beaconUrl: 'https://rum-ingest.us0.signalfx.com/v1/rum',
      rumAuth: 'ABC123โ€ฆ789',
      app: '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, // Disables monitoring for longtasks
         websockets: true, // Enables monitoring for websockets
      },
   });

The following table contains all the properties supported by the instrumentations option:

Property

Default

Description

connectivity

false

Enables the collection of connectivity events. See Connectivity.

document

true

Enables the collection of spans related to document load events. See Document load.

errors

true

Enables the collection of JavaScript errors. See Errors collected by the Browser RUM agent.

fetch

true

Enables the collection of Fetch API requests. See XHR and Fetch instrumentations.

interactions

true

Enables the collection of user interactions, such as clicks or key presses. See User interactions.

interactions.eventNames

Array of DOM events that the instrumentation captures as user interactions. You can access the default values by accessing the SplunkRum.DEFAULT_AUTO_INSTRUMENTED_EVENT_NAMES property.

longtask

true

Enables the collection of long tasks. See Long tasks.

socketio

false

Enables the collection of socket.io messages. See Socket.io messages.

postload

true

Enables the collection of resources loaded after a load event. See Resources after load.

socketio.target

'io'

The global variable name to which the socket.io client is loaded, or the io object. See Socket.io messages.

visibility

false

Enables the collection of visibility events. See Visibility.

websockets

false

Enables the collection of websocket lifecycle events. See Websockets.

webvitals

true

Enables the collection of Google Web Vitals metrics. See Web Vitals.

xhr

true

Enables the collection of XMLHttpRequest events. See XHR and Fetch instrumentations.

Sampling settings ๐Ÿ”—

By default, the Browser RUM 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:

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

   SplunkRum.init({
      beaconUrl: 'https://rum-ingest.<realm>.signalfx.com/v1/rum',
      rumAuth: '<your_rum_token>',
      app: '<application-name>',
      tracer: {
         sampler: shouldTrace ? new AlwaysOnSampler() : new SplunkRum.AlwaysOffSampler(),
      },
   });
</script>

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

Sampler

Description

AlwaysOnSampler

Sampling enabled for all requests. This is the default sampler.

AlwaysOffSampler

Sampling disabled for all requests.

ParentBasedSampler

Inherits the sampler configuration of the parent trace.

SessionBasedSampler

Session-based sampling. See Session-based sampler.

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:

Option

Type

Default value

Description

ratio

number

1.0

Percentage of sessions reported, ranging from 0.0 to 1.0.

sampled

Sampler

AlwaysOnSampler

Sampler to be used when the session is sampled.

notSampled

Sampler

AlwaysOffSampler

Sampler to be used when the session is not to be sampled.

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

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

Asynchronous trace settings ๐Ÿ”—

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 Browser RUM 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

To enable asynchronous traces, set the context.async property to true.

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.

Limitations ๐Ÿ”—

The following limitations apply when using asynchronous tracing:

  • async/await functions arenโ€™t supported. You can connect them using Babel as in the following example:

    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.

Context propagation settings ๐Ÿ”—

The Browser RUM 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 Browser RUM agent.

Exporter settings ๐Ÿ”—

The Browser RUM agent uses the Zipkin exporter to send data to Splunk Observability Cloud. The following example shows how to register a different trace exporter:

import SplunkRum from '@splunk/otel-web';
import {BatchSpanProcessor} from '@opentelemetry/sdk-trace-base';
import {CollectorTraceExporter} from '@opentelemetry/exporter-collector';

const exporter = new CollectorTraceExporter({ url: 'https://collector.example.com' });
SplunkRum.provider.addSpanProcessor(new BatchSpanProcessor(exporter));

Cookies used by the Browser RUM agent ๐Ÿ”—

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

Name

Purpose

Comment

__splunk_rum_sid

Stores the session ID.

By default, a session lasts for 15 minutes after the last user interaction. The maximum session duration is 4 hours.