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
	},
})
  1. Download the new agent from the CDN or NPM repository.

    Best practice is to use the latest version, 0.23.1.

    CDN
    BASH 
    background-service.html:
<script src="https://cdn.signalfx.com/o11y-gdi-rum/v2.1.0/background-service.html" integrity="sha384-XJGfg0ZTiemi+P19rBpkgMvQfSv4KUMjyDYesQr+Sb2DufnHtpV1ZNDdtCQqAXkw" crossorigin="anonymous"></script>
splunk-otel-web-session-recorder.js:
<script src="https://cdn.signalfx.com/o11y-gdi-rum/v2.1.0/splunk-otel-web-session-recorder.js" integrity="sha384-0mVnL5yVkIGmvif7SGWJHQJ43fg/WP5b23I93XYDguBGTJSax/9Teuoncc1BovHR" crossorigin="anonymous"></script>
splunk-otel-web.js:
<script src="https://cdn.signalfx.com/o11y-gdi-rum/v2.1.0/splunk-otel-web.js" integrity="sha384-OL3JYH6lxvFNUBrB+mo6kk0P8fBZNMulljO8jKzw6UNpRMwPb98qCEY36lZUL9mE" 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')