Splunk OpenTelemetry JavaScript for Web

🚀 Get Started • 📖 Documentation • 🤝 Contributing • 🛠️ Troubleshooting • 📜 License

---

Important

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

The official Splunk documentation for this repository is Instrument browser-based web applications for Splunk RUM.

Gain insights into the issues affecting real users of your front-end browser and mobile applications with Splunk Real User Monitoring (RUM). This repository contains several packages that provide core instrumentation, session recording, and build tooling to accelerate RUM adoption.

📦 Packages

Package	Description	Version	Documentation
@splunk/otel-web	Core RUM Library - Automated instrumentation for page loads, network requests, errors, Web Vitals, user interactions		📖 README
@splunk/otel-web-session-recorder	Session Replay - Privacy-aware visual session recording with timeline correlation for synchronized debugging		📖 README
@splunk/rum-build-plugins	Build Integration - Webpack plugins for automated source map uploads and enhanced debugging		📖 README

🚀 Quick Start

1. Install RUM Packages

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

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

# Using yarn
yarn add @splunk/otel-web @splunk/otel-web-session-recorder

2. Initialize RUM packages

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

SplunkRum.init({
	realm: 'us1', // Your Splunk realm (us0, us1, eu0, etc.)
	rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
	applicationName: 'my-app',
	deploymentEnvironment: 'production',
})

SplunkSessionRecorder.init({
	realm: 'us1',
	rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
})

3. Configure source map upload (optional)

npm install --save-dev @splunk/rum-build-plugins

// webpack.config.js
const { SplunkRumWebpackPlugin } = require('@splunk/rum-build-plugins')

module.exports = {
	devtool: 'source-map', // Required for source map upload
	plugins: [
		new SplunkRumWebpackPlugin({
			sourceMaps: {
				realm: 'us1',
				token: process.env.SPLUNK_ORG_ACCESS_TOKEN,
				disableUpload: process.env.NODE_ENV !== 'production',
			},
		}),
	],
}

📚 Documentation

• Getting Started Guide - Complete setup instructions
• Browser RUM Documentation - Advanced configuration and features
• API Reference - Detailed API documentation
• Examples - Integration examples for popular frameworks

🔧 Development

Prerequisites

• Node.js: >=22
• pnpm: >=10

Setup

# Clone the repository
git clone https://github.com/signalfx/splunk-otel-js-web.git
cd splunk-otel-js-web

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Start development mode
pnpm dev
# Sandbox available at http://localhost:3030

Commands

Command	Description
pnpm build	Build all packages
pnpm test	Run unit and integration tests
pnpm test:unit	Run unit tests only
pnpm test:e2e	Run end-to-end tests
pnpm lint	Run linting checks
pnpm lint:fix	Fix linting issues
pnpm dev	Start development watch mode

Local sandbox

pnpm dev serves a local playground for @splunk/otel-web at http://localhost:3030 for manual testing against a real Splunk realm or a local OTel collector. The pages live in packages/web/dev/ and are served by webpack-dev-server alongside the freshly-built SDK bundles.

The sandbox has two pages, switchable from the header nav:

• RUM (index.html) — exercise tracked fetch/XHR, history navigations, errors, custom spans, long tasks, and global attributes.

• Session Replay (replay.html) — drive the @splunk/otel-web-session-recorder against a rich set of DOM/canvas/iframe/video fixtures. Replay requires building the recorder first:

  pnpm --filter @splunk/otel-web-session-recorder build

Both pages share a Settings modal (gear icon) for realm, access token, app name, environment, beacon endpoints, and recorder options. Values (including the RUM access token) persist in localStorage per origin between reloads.

Realm presets via .env

To avoid re-typing tokens for common realms, copy packages/web/.env.example to packages/web/.env (git-ignored) and fill in dev/test tokens. The webpack DevPresetsPlugin reads the file on every compile and exposes the entries as a "Preset" dropdown in the Settings modal. Each block is keyed by a unique <ID>:

SPLUNK_RUM_REALM_<ID>            # realm (required; activates the preset)
SPLUNK_RUM_TOKEN_<ID>            # rumAccessToken
SPLUNK_RUM_APP_<ID>              # applicationName
SPLUNK_RUM_ENV_<ID>              # deploymentEnvironment
SPLUNK_RUM_BEACON_<ID>           # custom beaconEndpoint
SPLUNK_RUM_RECORDER_BEACON_<ID>  # custom recorder beaconEndpoint

Multiple presets can target the same realm by using distinct <ID> suffixes (e.g. US0, US0-2). Editing .env triggers a rebuild automatically.

Custom port

Set DEV_SERVE_PORT to override the default 3030:

DEV_SERVE_PORT=4000 pnpm dev

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up the development environment
• Code style and testing requirements
• Pull request process
• Issue reporting guidelines

🛠️ 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.