Docs » Instrument mobile and web applications for Splunk RUM » Instrument browser-based web applications for Splunk RUM » Install the Browser RUM agent for Splunk RUM

Install the Browser RUM agent for Splunk RUM πŸ”—

You can instrument the front end of your web applications for Splunk RUM using the Browser RUM agent from the Splunk Distribution of OpenTelemetry JavaScript for Web.

To instrument your browser application and get data into Splunk RUM, follow the instructions on this page.

Check compatibility and requirements πŸ”—

The Browser RUM agent instruments all front-end experiences that run in modern browsers, regardless of the JavaScript library or framework you use, with the following requirements:

  • All your pages, assets, and requests must be securely loaded over the HTTPS protocol.

  • Your application must not override standard methods.

The Browser RUM agent is compatible with the all the supported versions of the following browsers:

  • Google Chrome

  • Google Chrome for Android

  • Microsoft Edge

  • Mozilla Firefox

  • Apple Safari

  • Apple Safari for iOS

  • Chromium-based browsers

Microsoft Internet Explorer 11 is supported by a separate legacy build, available as splunk-otel-web-legacy.js in the release assets on GitHub .

Note

Splunk APM is not required to instrument Splunk RUM for Browser.

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.

Installation method

Use cases

Considerations

Splunk CDN

Multi-page websites

Quick integration with your site or applciation. Ad-blockers might interfere with loading.

Self-hosted script

Multi-page websites

Provides greater control over the installation. Updates are entirely manual.

npm package

Single-page applications

Bundles into your web application. Must be loaded as soon as possible. See Loading and initializing the Browser RUM agent for more information.

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 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 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.

Caution

Don’t use the latest version in production without prior testing.

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>
    
  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 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.

Note

Make sure the Splunk RUM agent doesn’t run in Node.js. To instrument Node.js services for Splunk APM, see Instrument Node.js applications for Splunk Observability Cloud.

Loading and initializing 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.

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.

Instrument WebViews in Mobile applications πŸ”—

You can instrument WebViews in your iOS and Android applications by sharing the splunk.rumSessionId 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:

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 app.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.