@splunk/otel-web

🚀 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 and Instrument browser-based web applications for Splunk RUM.

Splunk RUM for Browser collects performance metrics, web vitals, errors, and other forms of data for every user session to enable you to detect and troubleshoot problems in your application. For a complete view of your application from browser to back-end, integrate with Splunk APM.

🚀 Installation & Setup

Package Manager Installation

1. Install the Package

npm install @splunk/otel-web
# or
pnpm add @splunk/otel-web
# or
yarn add @splunk/otel-web

2. Initialize RUM

import { SplunkRum } from '@splunk/otel-web'

SplunkRum.init({
    realm: 'us1', // Your Splunk realm
    rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN', // RUM access token
    applicationName: 'my-web-app', // Application identifier
    deploymentEnvironment: 'production', // Environment (dev, staging, prod)
})

CDN Installation

1. Load the Script

<script
    src="https://cdn.signalfx.com/o11y-gdi-rum/<version>/splunk-otel-web.js"
    crossorigin="anonymous"
    integrity="sha384-<integrity>"
></script>

Replace <version> and <integrity> with the values from GitHub Releases.

2. Initialize RUM

<script>
    SplunkRum.init({
        realm: 'us1', // Your Splunk realm
        rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN', // RUM access token
        applicationName: 'my-web-app', // Application identifier
        deploymentEnvironment: 'production', // Environment (dev, staging, prod)
    })
</script>

Complete CDN Example

<!DOCTYPE html>
<html>
    <head>
        <title>My Web App</title>
        <!-- Load Splunk RUM -->
        <script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js"></script>
        <script>
            SplunkRum.init({
                realm: 'us1',
                rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
                applicationName: 'my-web-app',
                deploymentEnvironment: 'production',
                debug: false, // Set to true for development
            })
        </script>
    </head>
    <body>
        <!-- Your app content -->
    </body>
</html>

⚙️ Configuration Options

Option	Type	Required	Default	Description
`realm`	`string`	✅	-	Splunk realm (us0, us1, eu0, etc.)
`rumAccessToken`	`string`	✅	-	Publicly-visible RUM access token
`applicationName`	`string`	❌	`'unknown-browser-app'`	Application name identifier
`deploymentEnvironment`	`string`	❌	-	Sets the `environment` attribute
`version`	`string`	❌	-	Sets the `app.version` attribute
`beaconEndpoint`	`string`	❌	-	Custom destination URL (overrides realm)
`debug`	`boolean`	❌	`false`	Enable internal debug logging
`cookieDomain`	`string`	❌	`window.location.hostname`	Domain for session cookies
`ignoreUrls`	`Array<string\|RegExp>`	❌	`[]`	URLs to exclude from tracing
`globalAttributes`	`Attributes`	❌	`{}`	Attributes added to every span
`persistence`	`'cookie'\|'localStorage'`	❌	`'cookie'`	Where to store session data
`disableAutomationFrameworks`	`boolean`	❌	`false`	Block automation frameworks
`disableBots`	`boolean`	❌	`false`	Block bots (Google bot, Bing bot, etc.)
`user.trackingMode`	`'noTracking'\|'anonymousTracking'`	❌	`'noTracking'`	User tracking behavior
`exporter.otlp`	`boolean`	❌	`false`	Use OTLP format instead of Zipkin
`exporter.onAttributesSerializing`	`function`	❌	-	Transform attributes before export
Instrumentations
`instrumentations.connectivity`	`boolean\|Config`	❌	`false`	Network connectivity monitoring
`instrumentations.document`	`boolean\|Config`	❌	`true`	Document load instrumentation
`instrumentations.errors`	`boolean\|Config`	❌	`true`	Error capture
`instrumentations.fetch`	`boolean\|Config`	❌	`true`	Fetch API monitoring
`instrumentations.interactions`	`boolean\|Config`	❌	`true`	User interaction tracking
`instrumentations.longtask`	`boolean\|Config`	❌	`true`	Long task detection (>50ms)
`instrumentations.postload`	`boolean\|Config`	❌	`true`	Post-load resource timing
`instrumentations.socketio`	`boolean\|Config`	❌	`false`	Socket.IO client monitoring
`instrumentations.visibility`	`boolean\|Config`	❌	`false`	Page visibility changes
`instrumentations.webvitals`	`boolean\|Config`	❌	`true`	Web Vitals collection
`instrumentations.websocket`	`boolean\|Config`	❌	`false`	WebSocket monitoring
`instrumentations.xhr`	`boolean\|Config`	❌	`true`	XMLHttpRequest monitoring

Complete Configuration Example

import { SplunkRum } from '@splunk/otel-web'

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

    // Application identification
    applicationName: 'my-web-app',
    deploymentEnvironment: 'production',
    version: '1.2.3',

    cookieDomain: window.location.hostname,
    persistence: 'cookie',
    ignoreUrls: [/\/health-check/, '/analytics/track', 'https://third-party-ads.com'],

    // Global attributes for all spans
    globalAttributes: {
        'team': 'frontend',
        'feature.flag.checkout': 'enabled',
    },

    // Bot detection
    disableAutomationFrameworks: true,
    disableBots: true,

    // User tracking
    user: {
        trackingMode: 'anonymousTracking',
    },

    // Export options
    exporter: {
        otlp: true, // Use OTLP instead of Zipkin
        onAttributesSerializing: (attributes, span) => {
            // Remove or hash sensitive data
            if (attributes['http.url']) {
                attributes['http.url'] = sanitizeUrl(attributes['http.url'])
            }
            return attributes
        },
    },

    // Instrumentation control
    instrumentations: {
        // Core instrumentations (enabled by default)
        document: true,
        errors: true,
        fetch: true,
        interactions: true,
        longtask: true,
        postload: true,
        webvitals: true,
        xhr: true,

        // Optional instrumentations (disabled by default)
        connectivity: false,
        socketio: false,
        visibility: false,
        websocket: false,
    },

    // Development
    debug: process.env.NODE_ENV !== 'production',
})

📚 API Reference

SplunkRum Class

Static Methods

Method	Parameters	Returns	Description
`init(config)`	`SplunkRumConfig`	`void`	Initialize the RUM SDK
`setGlobalAttributes(attrs)`	`Attributes`	`void`	Add global span attributes
`getSessionId()`	-	`string`	Get current session ID

Properties

Property	Type	Description
`provider`	`TracerProvider`	OpenTelemetry tracer provider

🛠️ Troubleshooting

For troubleshooting issues with the Splunk Distribution of OpenTelemetry JS for Web, see Troubleshoot browser instrumentation for Splunk Observability Cloud in the official documentation.

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