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 supports the following browser versions:

  • Chrome and Chrome Android 51 and higher

  • Edge 12 and higher

  • Firefox 36 and higher

  • Safari and Safari iOS 10.1 and higher

  • Internet Explorer 11

Internet Explorer 11 requires the splunk-otel-web-legacy.js version of the Browser RUM agent.

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

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:

Tip: To generate all the installation commands for your environment and application, use the Browser Instrumentation guided setup. To access the Browser Instrumentation guided setup, follow these steps:

  1. Log in to Observability Cloud.

  2. In the left navigation menu, select Data Management.

  3. Select Add Integration to open the Integrate Your Data page.

  4. In the integration filter menu, select By Use Case.

  5. Select the Monitor user experience use case.

  6. Select the Browser Instrumentation tile to open the Browser Instrumentation guided setup.

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.

Follow these steps to instrument your application with the CDN:

  1. Customize the following snippet:

    <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: '<your_app_name>',
          version: '<your_app_version>',
          environment: '<your_environment_name>'
       });
    </script>
    
    • In the beacon URL, realm is the Observability Cloud realm, for example, us0. To find the realm name of your account, follow these steps:

      1. Open the left navigation menu in 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.

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({
          beaconUrl: 'https://rum-ingest.<realm>.signalfx.com/v1/rum',
          rumAuth: '<your_rum_token>',
          app: '<your_app_name>',
          version: '<your_app_version>',
          environment: '<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.

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({
       beaconUrl: 'https://rum-ingest.<realm>.signalfx.com/v1/rum',
       rumAuth: '<your_rum_token>',
       app: '<your_application_name>',
       version: '<your_app_version>',
       environment: '<your_environment_name>'
    });
    
    • In the beacon URL, realm is the Observability Cloud realm, for example, us0. To find the realm name of your account, follow these steps:

      1. Open the left navigation menu in 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.

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, disable 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({
      beaconUrl: 'https://rum-ingest.<realm>.signalfx.com/v1/rum',
      rumAuth: '<your_rum_token>',
      app: '<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).

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

Versioning policy πŸ”—

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

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