@splunk/otel-web-session-recorder
Advanced tools
🚀 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.
# 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
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',
})
Choose a versioning strategy based on your needs:
Major Version Lock (Recommended)
<!-- Locks to v1.x.x - gets latest minor and patch updates -->
<script src="https://cdn.signalfx.com/o11y-gdi-rum/v1/splunk-otel-web.js" crossorigin="anonymous"></script>
<script
src="https://cdn.signalfx.com/o11y-gdi-rum/v1/splunk-otel-web-session-recorder.js"
crossorigin="anonymous"
></script>
Minor Version Lock
<!-- Locks to v1.0.x - gets latest patch updates only -->
<script src="https://cdn.signalfx.com/o11y-gdi-rum/v1.1/splunk-otel-web.js" crossorigin="anonymous"></script>
<script
src="https://cdn.signalfx.com/o11y-gdi-rum/v1.1/splunk-otel-web-session-recorder.js"
crossorigin="anonymous"
></script>
Exact Version Lock
<!-- Locks to exact version v1.1.0 - no automatic updates -->
<script
src="https://cdn.signalfx.com/o11y-gdi-rum/v1.1.0/splunk-otel-web.js"
crossorigin="anonymous"
integrity="sha384-<integrity>"
></script>
<script
src="https://cdn.signalfx.com/o11y-gdi-rum/v1.1.0/splunk-otel-web-session-recorder.js"
crossorigin="anonymous"
integrity="sha384-<integrity>"
></script>
Latest Version (Not Recommended)
<!-- Always pulls the latest released version -->
<script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
<script
src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web-session-recorder.js"
crossorigin="anonymous"
></script>
⚠️ Warning: Using
latestautomatically 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.
<script>
// 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',
})
</script>
<!DOCTYPE html>
<html>
<head>
<title>My Web App with Session Recording</title>
<!-- Load Splunk RUM (using major version lock) -->
<script src="https://cdn.signalfx.com/o11y-gdi-rum/v1/splunk-otel-web.js" crossorigin="anonymous"></script>
<!-- Load Session Recorder (using major version lock) -->
<script
src="https://cdn.signalfx.com/o11y-gdi-rum/v1/splunk-otel-web-session-recorder.js"
crossorigin="anonymous"
></script>
<script>
// Initialize 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',
debug: false, // Set to true for development
})
</script>
</head>
<body>
<!-- Your app content -->
</body>
</html>
⚠️ Important: Always call
SplunkRum.init()beforeSplunkSessionRecorder.init().
| 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 |
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' },
],
})
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:
// 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/<version>/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.htmlinnode_modules/@splunk/otel-web-session-recorder/dist/artifactsto copy to your static assets or usetrueand load it from CDN.
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,
},
},
},
})
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
})
For troubleshooting issues with the Splunk Session Recorder, see Troubleshoot browser instrumentation for Splunk Observability Cloud in the official documentation.
| Method | Parameters | Returns | Description |
|---|---|---|---|
init(config) | SessionRecorderConfig | void | Initialize session recorder |
start() | - | void | Start recording current session |
stop() | - | void | Stop recording current session |
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<string, string>
}
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.
FAQs
Session recorder for Splunk Observability
The npm package @splunk/otel-web-session-recorder receives a total of 3,795 weekly downloads. As such, @splunk/otel-web-session-recorder popularity was classified as popular.
We found that @splunk/otel-web-session-recorder demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 14 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CTO Ahmad Nassri discusses why supply chain attacks now target developer machines and what AI means for the future of enterprise security.
Security News
Learn the essential steps every developer should take to stay secure on npm and reduce exposure to supply chain attacks.
Security News
Experts push back on new claims about AI-driven ransomware, warning that hype and sponsored research are distorting how the threat is understood.