Upgrade the Splunk RUM browser agent

Upgrade your applications and build environment to use a newer version of the Splunk RUM browser agent.

Your browser applications are using a pre-1.0.0 version of the Splunk RUM browser agent. Version 1.0.0 marks the first stable release of the Splunk OpenTelemetry JavaScript Web SDK. This release graduates the SDK out of beta, removes deprecated APIs, introduces stable replacements, and improves session management and recording.

This guide walks you through breaking changes and provides code examples for upgrading from older versions.

Breaking changes in version 1.0.0

Version 1.0.0 of the Splunk RUM for browser agent contains the following updates:

Removed deprecated agent configuration options and APIs

Deprecated agent configuration options:

Option Replacement
app applicationName
beaconUrl beaconEndpoint
environment deploymentEnvironment
rumAuth rumAccessToken
_experimental_allSpansExtendSession None
_experimental_longtaskNoStartSession None

Deprecated agent APIs, including _experimental_* APIs:

API (method) Replacement
SplunkRum.error() SplunkRum.reportError()
SplunkRum._experimental_addEventListener() SplunkRum.addEventListener()
SplunkRum._experimental_getGlobalAttributes() SplunkRum.getGlobalAttributes()
SplunkRum._experimental_getSessionId() SplunkRum.getSessionId()
SplunkRum._experimental_removeEventListener() SplunkRum.removeEventListener()
Changes to supported browsers
  • Removed support for Internet Explorer and other legacy browsers
  • Removed the legacy build
Changes to the session lifecycle module
  • Sessions now extend only on click, scroll, touch, and keydown events
  • Removed configuration options _experimental_allSpansExtendSession and _experimental_longtaskNoStartSession
Changes to the session recorder module
  • The agent now uses the new built-in session recorder module and has removed the rrweb module and its dependency. See Record browser sessions.
  • Removed the module configuration option recorderType
  • Failed replay data is now stored in local storage (limit: 2MB) and re-sent after reload

Breaking changes in version 2.0.0

If you haven't already done so, upgrade your applications for the breaking changes introduced in version 1.0.0. Version 2.0.0 doesn't introduce breaking changes in the traditional sense, but it does activate anonymous user ID tracking, which might be a breaking change for you, since the data is stored in a cookie. To deactivate this, update your configuration options:

JAVASCRIPT 
SplunkRum.init({
	realm: 'your-splunk-realm',
	rumAccessToken: 'your-splunk-rum-access-token',
	user: {
		trackingMode: 'noTracking', // Opt out of anonymous tracking
	},
})

Breaking changes in version 3.0.0

Domain migration from signalfx.com to observability.splunkcloud.com
All endpoints have moved to new domains:
Old domain Replacement

cdn.signalfx.com

cdn.observability.splunkcloud.com
rum-ingest.{realm}.signalfx.com rum-ingest.{realm}.observability.splunkcloud.com
api.{realm}.signalfx.com api.{realm}.observability.splunkcloud.com
rum-ingest.{realm}.signalfx.com rum-ingest.{realm}.observability.splunkcloud.com
Content Security Policy (CSP)
If your application uses a content security policy (CSP), update these directives before upgrading:
Directive What to update
script-src Add cdn.observability.splunkcloud.com to load the agent and session replay using CDN
connect-src Add rum-ingest.{realm}.observability.splunkcloud.com
The old signalfx.com domains can be removed from your policy after all agents are upgraded.
Discontinuing latest CDN tag
The latest tag will not receive any future updates. Migrate to a versioned URL on the new CDN domain to use the most updated version:
CODE 
<script src="https://cdn.observability.splunkcloud.com/o11y-gdi-rum/v3/splunk-otel-web.js"></script>
Available version locks:
  • v3 — major version lock (recommended), receives all minor and patch updates
  • v3.0 — minor version lock, receives patch updates only
  • v3.0.0 — exact version pin
OTLP exporter enabled by default
  • OTLP is now the default export format when beaconEndpoint is not specified. Set exporter.otlp: false to opt out of this default.
  • A deprecation warning displays when beaconEndpoint is provided without exporter.otlp: true
  • spaMetrics now defaults to true. SPA route metrics are collected by default.

Experimental flags enabled by default
  • LCP, CLS, and INP spans are anchored to the documentLoad span timestamp by default
    Option Replacement
    _experimental_adjustSessionStartToTimeOrigin adjustSessionStartToTimeOrigin
    _experimental_discardDataAfterInactivity discardDataAfterInactivity
    experimental_alignWebVitalsSpansWithDocumentLoad instrumentations.webvitals.alignWebVitalsSpansWithDocumentLoad

Upgrade steps

Note: You can use the legacy or new API and service endpoint URLs as of March 24, 2026. The legacy endpoints have the domain signalfx, and the new endpoints have the domain observability.splunkcloud. Thus, you can use the legacy ingest endpoint ingest.realm.signalfx.com or the new ingest endpoint ingest.realm.observability.splunkcloud.com. See Splunk Observability Cloud domain change for more information.
  1. Download the new agent from the CDN or NPM repository.

    Best practice is to use the latest version.

    CDN
    BASH 
    splunk-otel-web.js:
<script src="https://cdn..com/o11y-gdi-rum/v3.0.0/splunk-otel-web.js" integrity="sha384-OL3JYH6lxvFNUBrB+mo6kk0P8fBZNMulljO8jKzw6UNpRMwPb98qCEY36lZUL9mE" crossorigin="anonymous"></script>
splunk-otel-web-session-recorder.js:
<script src="https://cdn.observability.splunkcloud.com/o11y-gdi-rum/v3.0.0/splunk-otel-web-session-recorder.js" integrity="sha384-0mVnL5yVkIGmvif7SGWJHQJ43fg/WP5b23I93XYDguBGTJSax/9Teuoncc1BovHR" crossorigin="anonymous"></script>
    NPM
    BASH 
    npm i @splunk/otel-web
  2. Update your configuration options as in the example below.

    Before:

    JAVASCRIPT 
    SplunkRum.init({
  app: 'your-application-name',
  beaconUrl: 'https://...',
  environment: 'your-environment-name',
  rumAuth: 'your-splunk-rum-access-token',
})

    After:

    JAVASCRIPT 
    SplunkRum.init({
  applicationName: 'your-application-name',
  beaconEndpoint: 'https://...',
  deploymentEnvironment: 'your-environment-name',
  rumAccessToken: 'your-splunk-rum-access-token',
})
  3. Update your API calls as in the example below.

    Before:

    JAVASCRIPT 
    SplunkRum._experimental_getGlobalAttributes()
SplunkRum.error('Something went wrong')

    After:

    JAVASCRIPT 
    SplunkRum.getGlobalAttributes()
SplunkRum.reportError('Something went wrong')