@splunk/otel-web

v1.2.0

Published

4 days ago

Splunk distribution of Open Telemetry for browser environment.

Downloads

74,707

@splunk/otel-web

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

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>

Minor Version Lock

<!-- Locks to v1.1.x - gets latest patch updates only -->
<script src="https://cdn.signalfx.com/o11y-gdi-rum/v1.1/splunk-otel-web.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>

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>

⚠️ Warning: Using latest automatically pulls the newest released version of the RUM agent, 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

<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 (using major version lock) -->
		<script src="https://cdn.signalfx.com/o11y-gdi-rum/v1/splunk-otel-web.js" crossorigin="anonymous"></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 | ---------------------------------- | realm | rumAccessToken | applicationName | deploymentEnvironment | version | beaconEndpoint | debug | cookieDomain | ignoreUrls | globalAttributes | persistence | disableAutomationFrameworks | disableBots | user.trackingMode | exporter.otlp | exporter.onAttributesSerializing | privacy.maskAllText | privacy.sensitivityRules | Instrumentations | instrumentations.connectivity | instrumentations.document | instrumentations.errors | instrumentations.fetch | instrumentations.interactions | instrumentations.longtask | instrumentations.postload | instrumentations.socketio | instrumentations.visibility | instrumentations.webvitals | instrumentations.websocket | instrumentations.xhr | Type | Required | Default | Description | | ----------------------------------- | -------- | -------------------------- | ---------------------------------------- | | string | ✅ | - | Splunk realm (us0, us1, eu0, etc.) | | string | ✅ | - | Publicly-visible RUM access token | | string | ❌ | 'unknown-browser-app' | Application name identifier | | string | ❌ | - | Sets the environment attribute | | string | ❌ | - | Sets the app.version attribute | | string | ❌ | - | Custom destination URL (overrides realm) | | boolean | ❌ | false | Enable internal debug logging | | string | ❌ | window.location.hostname | Domain for session cookies | | Array<string\|RegExp> | ❌ | [] | URLs to exclude from tracing | | Attributes | ❌ | {} | Attributes added to every span | | 'cookie'\|'localStorage' | ❌ | 'cookie' | Where to store session data | | boolean | ❌ | false | Block automation frameworks | | boolean | ❌ | false | Block bots (Google bot, Bing bot, etc.) | | 'noTracking'\|'anonymousTracking' | ❌ | 'noTracking' | User tracking behavior | | boolean | ❌ | false | Use OTLP format instead of Zipkin | | function | ❌ | - | Transform attributes before export | | boolean | ❌ | true | Mask all text from text nodes | | Array<SensitivityRule> | ❌ | [] | Rules for text sensitivity by selector | | | | | | | boolean\|Config | ❌ | false | Network connectivity monitoring | | boolean\|Config | ❌ | true | Document load instrumentation | | boolean\|Config | ❌ | true | Error capture | | boolean\|Config | ❌ | true | Fetch API monitoring | | boolean\|Config | ❌ | true | User interaction tracking | | boolean\|Config | ❌ | true | Long task detection (>50ms) | | boolean\|Config | ❌ | true | Post-load resource timing | | boolean\|Config | ❌ | false | Socket.IO client monitoring | | boolean\|Config | ❌ | false | Page visibility changes | | boolean\|Config | ❌ | true | Web Vitals collection | | boolean\|Config | ❌ | false | WebSocket monitoring | | boolean\|Config | ❌ | true | XMLHttpRequest monitoring |

Privacy Configuration

The privacy configuration allows you to control how text content is collected from user interactions:

maskAllText: When true (default), all text from text nodes is masked unless an unmask rule applies
sensitivityRules: Array of rules that determine text sensitivity based on CSS selectors. Rules are applied in order, with later rules overriding earlier ones

Rule Types:

mask: Mask text content in matching elements
unmask: Unmask text content in matching elements
exclude: Exclude matching elements from text collection entirely

Example:

privacy: {
  maskAllText: true,
  sensitivityRules: [
    { rule: 'unmask', selector: '.public-content' },
    { rule: 'exclude', selector: '.sensitive-data' },
    { rule: 'mask', selector: '.public-content .private-info' }
  ]
}

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',
	},

	// Privacy configuration
	privacy: {
		maskAllText: true, // Mask all text from text nodes by default
		sensitivityRules: [
			// Unmask text in specific elements
			{ rule: 'unmask', selector: '.public-content' },
			{ rule: 'unmask', selector: 'h1, h2, h3' },
			// Exclude sensitive elements entirely
			{ rule: 'exclude', selector: '.sensitive-data' },
			// Override previous rules for specific cases
			{ rule: 'mask', selector: '.public-content .private-info' },
		],
	},

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@splunk/otel-web

🚀 Installation & Setup

Package Manager Installation

1. Install the Package

2. Initialize RUM

CDN Installation

1. Load the Script

2. Initialize RUM

Complete CDN Example

⚙️ Configuration Options

Privacy Configuration

Complete Configuration Example

📚 API Reference

SplunkRum Class

Static Methods

Properties

🛠️ Troubleshooting

📜 License