Check compatibility and requirements

Instrument your web application for Splunk RUM

Before you instrument and configure Splunk RUM for your web application, understand which data RUM collects about your application and determine the scope of what you want to monitor. See Data collected by Splunk RUM.

Select one of the following methods to instrument your web application.

Splunk CDN

You can use the Splunk Content Delivery Network (CDN) to load the Browser RUM agent synchronously. The CDN link ensures that your application always uses the latest version.

Decide which version to run in your environment

The versioning of the Browser RUM agent follows semantic versioning rules. To have more control over the version you load, see the following versioning policy:

• Use the latest version to use the latest version of the Browser RUM agent. In preproduction, use latest to try out the most recent version of Splunk RUM. Don’t use in production environments without prior testing. This version might not be suitable for manual instrumentation, as breaking API changes might occur between major version changes.

• Use major versions, for example v1, if you want to receive new features automatically while keeping backward compatibility with the API. This is the default for all production deployments, as well as for npm installations.

• Use minor versions, for example v1.1, to receive bug fixes while not receiving new features automatically.

• Use patch versions, for example, v1.2.1, to pin a specific version of the agent for your application.

The versions of the agent are included in URLs as a designated token. For example:

https://cdn.signalfx.com/o11y-gdi-rum/v<MAJOR.MINOR.PATCH>/splunk-otel-web.js

In production environments, use the pinned version which was previously tested in preproduction and update the production version on a monthly cycle.

Add the CDN script to your application

Follow these steps to instrument your application with the CDN:

1. Customize the following snippet:

   <!--//
   
   IMPORTANT: Replace the <version> placeholder in the src URL with a
   version from https://github.com/signalfx/splunk-otel-js-web/releases
   
   //-->
   <script src="https://cdn.signalfx.com/o11y-gdi-rum/<version>/splunk-otel-web.js" crossorigin="anonymous"></script>
   <script>
      SplunkRum.init({
         realm: '<realm>',
         rumAccessToken: '<your_rum_token>',
         applicationName: '<your_app_name>',
         version: '<your_app_version>',
         deploymentEnvironment: '<your_environment_name>'
      });
   </script>

   • In the URL of the script, replace <version> with a version from the Releases page in GitHub .

   • realm is the Splunk Observability Cloud realm, for example, us0. To find your Splunk realm, see Note about realms.

   • To generate a RUM access token, see Generate your RUM access token in Splunk Observability Cloud.

2. Add the snippet to the head section of every page you want to monitor in your application.

3. Deploy the changes to your application. Make sure to test the instrumentation in a pre-production environment before deploying to production.

Self-hosted script

To use your own CDN or comply with your own deployment requirements, instrument your application using a self-hosted script. When you host the script, you need to update to newer versions of the agent manually.

Follow these steps to instrument your application using a self-hosted script:

1. Go to splunk-otel-js-web in GitHub and download the splunk-otel-web.js file for the release you want to use.

2. Deploy the files in a location accessible by the users of your application.

3. Customize the following snippet:

   <script src="http://example.domain/path/splunk-otel-web.js"></script>
   <script>
      SplunkRum.init({
         realm: '<realm>',
         rumAccessToken: '<your_rum_token>',
         applicationName: '<your_app_name>',
         version: '<your_app_version>',
         deploymentEnvironment: '<your_environment_name>'
      });
   </script>

   • realm is the Splunk Observability Cloud realm, for example, us0. See Realms in endpoints .

   • To generate a RUM access token, see Generate your RUM access token in Splunk Observability Cloud.

4. Add the snippet to the head section of every page you want to monitor in your application.

5. Deploy the changes to your application. Make sure to test the instrumentation in a pre-production environment before deploying to production.

npm package

To bundle the Browser RUM agent directly with your application, use the @splunk/otel-web npm package.

Follow these steps to instrument and configure Splunk RUM using npm:

1. Enter the following command to install the Browser RUM agent and add it to your package.json file:

   npm install @splunk/otel-web --save

2. Create the splunk-instrumentation.js initialization file next to your bundle root file. The following snippet contains sample content for the initialization file:

   import SplunkOtelWeb from '@splunk/otel-web';
   SplunkOtelWeb.init({
      realm: '<realm>',
      rumAccessToken: '<your_rum_token>',
      applicationName: '<your_application_name>',
      version: '<your_app_version>',
      deploymentEnvironment: '<your_environment_name>'
   });

   • realm is the Splunk Observability Cloud realm, for example, us0. To find the realm name of your account, follow these steps:

     1. Open the navigation menu in Splunk Observability Cloud.

     2. Select Settings.

     3. Select your username.

     The realm name appears in the Organizations section.

   • To generate a RUM access token, see Generate your RUM access token in Splunk Observability Cloud.

3. Import or require the splunk-instrumentation.js file before other files to ensure that the instrumentation runs before the application code.

4. Deploy the changes to your application. Make sure to test the instrumentation in a pre-production environment before deploying to production.

Load and initialize the Browser RUM agent

To avoid gaps in your data, load and initialize the Browser RUM agent synchronously and as early as possible. Delayed loading might result in missing data, as the instrumentation cannot collect data before it’s initialized.

Use one the following methods to load and initialize the Browser RUM agent, in order of effectiveness:

• Synchronously load the Browser RUM agent as the first resource, or at least the first JS resource, in the head section. The Browser RUM agent JavaScript file must be loaded before any other JS file. This ensures that the instrumentation collects all user interactions, resources, and errors.

• Bundle the Browser RUM agent with other application scripts. Place the Browser RUM agent at the top of the bundle and make sure the bundle loads synchronously.

If you defer the loading of the Browser RUM agent, make sure other scripts are also deferred to preserve the initialization order. Note that asynchronously loaded scripts are not supported.

Set up Session Replay

With Session Replay you can replay a session to take a look at exactly what the user experienced and make informed decisions about what to do next.

See Session replay in Splunk RUM for instructions on how to set up and configure Session Replay.

Customize your RUM data intake

You can customize the data intake for the Browser RUM agent to reduce noise and redact information.

Opt out of error.message collection

To avoid collecting error.message responses, deactivate the errors instrumentation as in the following example:

<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: '<your_app_name>',
      version: '<your_app_version>',
      instrumentations: { errors: false }
   });
</script>

Change attributes before they’re collected

To remove or change attributes in your spans, see Sanitize Personally Identifiable Information (PII).

Collect errors with single-page application frameworks

To collect errors when using single-page application frameworks, see Collect errors with single-page application frameworks.

Link RUM with Splunk APM

Splunk RUM uses server timing to calculate the response time between the front end and back end of your application, and to join the front-end and back-end traces for end-to-end visibility.

By default, the Splunk Distributions of OpenTelemetry already send the Server-Timing header. The header links spans from the browser with back-end spans and traces.

Instrument WebViews in Mobile applications

between the mobile instrumentation and the web instrumentation. This lets you see data from both your native app and your web app in a single stream.

To instrument WebViews, follow the instructions for the app’s operating system:

• Android WebViews

• iOS WebViews

Considerations for content security policy

If your application uses Content Security Policy (CSP) to mitigate potential impact from cross-site scripting (XSS) and other attacks, make sure the policy allows Splunk RUM to run:

• When using the CDN version of the agent, allow the script-src cdn.signalfx.com URL.

• When self-hosting or using the npm package, configure your site accordingly.

• Add the host from the beaconEndpoint property to the connect-src property. For example: connect-src rum-ingest.us1.signalfx.com.

How to contribute

The Splunk Distribution of OpenTelemetry JavaScript for Web is open-source software. You can contribute to its improvement by creating pull requests in GitHub. To learn more, see the contributing guidelines in GitHub.