@splunk/otel-web-session-recorder

🚀 Installation & Setup
•
⚙️ Configuration
•
🛠️ Troubleshooting
•
📚 API Reference

---

> For complete instructions for how to get started with the Splunk distribution of OpenTelemetry JavaScript for Web, see Install the Browser RUM agent for Splunk RUM, Instrument browser-based web applications for Splunk RUM and Record browser sessions.

Privacy-aware visual session replay for web applications. The Splunk Session Recorder extends @splunk/otel-web with comprehensive session recording capabilities, correlating visual user interactions with OpenTelemetry telemetry for enhanced debugging and user experience analysis.

🚀 Installation & Setup

$3

#### 1. Install the Packages

``bash


Install both core RUM and session recorder

npm install @splunk/otel-web @splunk/otel-web-session-recorder

or

pnpm add @splunk/otel-web @splunk/otel-web-session-recorder

or

yarn add @splunk/otel-web @splunk/otel-web-session-recorder
`

#### 2. Initialize RUM and Session Recorder

`typescript
import { SplunkRum } from '@splunk/otel-web'
import SplunkSessionRecorder from '@splunk/otel-web-session-recorder'

// Initialize core RUM first
SplunkRum.init({
realm: 'us1',
rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
applicationName: 'my-web-app',
deploymentEnvironment: 'production',
})

// Then initialize session recorder
SplunkSessionRecorder.init({
realm: 'us1',
rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
})
`

$3

#### 1. Load the Scripts

Choose a versioning strategy based on your needs:

Major Version Lock (Recommended)

`html


src="https://cdn.signalfx.com/o11y-gdi-rum/v2/splunk-otel-web-session-recorder.js"
crossorigin="anonymous"
>
`

Minor Version Lock

`html


src="https://cdn.signalfx.com/o11y-gdi-rum/v2.1/splunk-otel-web-session-recorder.js"
crossorigin="anonymous"
>
`

Exact Version Lock

`html

src="https://cdn.signalfx.com/o11y-gdi-rum/v2.1.0/splunk-otel-web.js"
crossorigin="anonymous"
integrity="sha384-"
>
src="https://cdn.signalfx.com/o11y-gdi-rum/v2.1.0/splunk-otel-web-session-recorder.js"
crossorigin="anonymous"
integrity="sha384-"
>
`

Latest Version (Not Recommended)

`html


src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web-session-recorder.js"
crossorigin="anonymous"
>
`

> ⚠️ Warning: Using latest automatically pulls the newest released version of the RUM agent and session recorder, which may introduce breaking changes without notice. This can cause unexpected behavior in production. Use a version lock strategy instead.

> 📖 For version numbers and integrity hashes, see GitHub Releases.
>
> 📚 For detailed CDN setup instructions, see the official documentation.

#### 2. Initialize RUM and Session Recorder

`html

`

#### Complete CDN Example

`html









src="https://cdn.signalfx.com/o11y-gdi-rum/v1/splunk-otel-web-session-recorder.js"
crossorigin="anonymous"
>







`

> ⚠️ Important: Always call SplunkRum.init() before SplunkSessionRecorder.init().

⚙️ Configuration Options

| Option | Type | Required | Default | Description |
| ---------------------------- | ---------------------------------------- | -------- | -------- | ---------------------------------------------------------- |
| realm | string | ✅ | - | Splunk realm (us0, us1, eu0, etc.) |
| rumAccessToken | string | ✅ | - | RUM access token for authentication |
| beaconEndpoint | string | ❌ | - | Custom destination URL for captured data (overrides realm) |
| debug | boolean | ❌ | false | Enable debug logging |
| persistFailedReplayData | boolean | ❌ | true | Store failed uploads in localStorage for retry |
| maskAllInputs | boolean | ❌ | true | Mask all form input values |
| maskAllText | boolean | ❌ | false | Mask all text content |
| sensitivityRules | SensitivityRule[] | ❌ | [] | Custom rules for masking, unmasking, or excluding elements |
| features.backgroundService | string \| boolean | ❌ | false | Custom URL for background service worker |
| features.canvas | boolean | ❌ | false | Record canvas elements |
| features.iframes | boolean | ❌ | false | Record iframe content |
| features.video | boolean | ❌ | false | Record video elements |
| features.cacheAssets | boolean | ❌ | true | Cache assets for replay |
| features.packAssets | boolean \| PackAssetsConfig | ❌ | true | Pack assets to reduce payload size |
| maxExportIntervalMs | number | ❌ | 5000 | Maximum interval between data exports (milliseconds) |
| logLevel | 'debug' \| 'info' \| 'warn' \| 'error' | ❌ | 'warn' | Logging level for session recorder |

$3

`typescript
interface SensitivityRule {
rule: 'mask' | 'unmask' | 'exclude'
selector: string // CSS selector
}

// Example usage
SplunkSessionRecorder.init({
realm: 'us1',
rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
sensitivityRules: [
{ rule: 'mask', selector: '.sensitive-data' },
{ rule: 'exclude', selector: '.payment-form' },
{ rule: 'unmask', selector: '.public-content' },
],
})
`

$3

The background service is used to offload session replay processing to a 3rd party iframe (separate thread), improving performance by preventing the session replay logic from blocking the main thread.
It is required for image compression - the background service handles compressing captured images to reduce payload size during session replay.

When to customize:

- Self-hosting the session recorder files
- Using a custom Content Security Policy (CSP)
- Deploying behind a firewall that blocks CDN access

`typescript
// Example: Self-hosted background service - ensure the domain is different from the main domain to ensure the background service is loaded in a separate thread.
SplunkSessionRecorder.init({
realm: 'us1',
rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
features: {
backgroundService: 'https://my-other-domain.com/assets/background-service.html',
},
})

// Example: spunk domain
// It will load an 3rd party iframe (background service) from this domain 'https://cdn.signalfx.com/o11y-gdi-rum//background-service.html'
// Ensure you have this domain whitelisted in your CSP config
SplunkSessionRecorder.init({
realm: 'us1',
rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
features: {
backgroundService: true,
},
})
`

> 💡 Default behavior: If not specified, asset processing is not offloaded and is handled on the main page thread.
>
> 📁 File location: When using npm installation, find background-service.html in node_modules/@splunk/otel-web-session-recorder/dist/artifacts to copy to your static assets or use true and load it from CDN.

$3

`typescript
interface PackAssetsConfig {
fonts?: boolean // Pack font assets
styles?: boolean // Pack CSS styles
images?:
| boolean
| {
onlyViewportImages?: boolean // Only pack visible images
pack?: boolean // Enable image packing
quality?: number // JPEG quality (0-1). Only available when backgroundService is set, otherwise silently ignored
}
}

// Example usage
SplunkSessionRecorder.init({
realm: 'us1',
rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
features: {
packAssets: {
fonts: true,
styles: true,
images: {
onlyViewportImages: true,
pack: true,
quality: 0.8,
},
},
},
})
`

$3

`typescript
import SplunkSessionRecorder from '@splunk/otel-web-session-recorder'

SplunkSessionRecorder.init({
// Required settings
realm: 'us1',
rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',

// Optional: Custom endpoint (overrides realm)
beaconEndpoint: 'https://custom-endpoint.com/v1/rumreplay',

// Privacy & Security
maskAllInputs: true,
maskAllText: false,
sensitivityRules: [
{ rule: 'exclude', selector: '.payment-form' },
{ rule: 'mask', selector: '.sensitive-data' },
{ rule: 'unmask', selector: '.public-info' },
],

// Feature Control
features: {
backgroundService: true,,
canvas: false, // Skip canvas recording for privacy
iframes: false, // Skip iframe content
video: false, // Skip video elements
cacheAssets: true, // Cache assets for better replay
packAssets: {
// Optimize asset packing
fonts: true,
styles: true,
images: {
onlyViewportImages: true,
pack: true,
quality: 0.7,
},
},
},

// Performance
maxExportIntervalMs: 5000, // Export data every 5 seconds
logLevel: 'warn', // Log warnings and errors only

// Advanced
debug: false, // Disable debug logging
persistFailedReplayData: true, // Store failed uploads for retry
})
`

🛠️ Troubleshooting

For troubleshooting issues with the Splunk Session Recorder, see Troubleshoot browser instrumentation for Splunk Observability Cloud in the official documentation.

📚 API Reference

$3

#### Static Methods

| Method | Parameters | Returns | Description |
| -------------- | ----------------------- | ------- | ------------------------------- |
| init(config) | SessionRecorderConfig | void | Initialize session recorder |
| start() | - | void | Start recording current session |
| stop() | - | void | Stop recording current session |

`typescript
interface SessionRecorderConfig {
// Required
realm: string
rumAccessToken: string

// Privacy
maskAllInputs?: boolean
maskAllText?: boolean
sensitivityRules?: SensitivityRule[]

// Feature Control
features?: {
backgroundService?: string | boolean
canvas?: boolean
iframes?: boolean
video?: boolean
cacheAssets?: boolean
packAssets?: boolean | PackAssetsConfig
}

// Performance
maxExportIntervalMs?: number
logLevel?: 'debug' | 'info' | 'warn' | 'error'

// Advanced
debug?: boolean
beaconEndpoint?: string
persistFailedReplayData?: boolean
}

interface SensitivityRule {
rule: 'mask' | 'unmask' | 'exclude'
selector: string
}

interface UserInfo {
id?: string
email?: string
attributes?: Record
}
``

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

---

> ℹ️  SignalFx was acquired by Splunk in October 2019. See Splunk SignalFx for more information.