Datadog SDK for Electron

Real User Monitoring for Electron applications.

Alpha (v0.X.X) — This SDK is in early development. APIs may change between releases.

Getting Started

Prerequisites

• Node.js 25+
• Electron 39+

Install

yarn add @datadog/electron-sdk
# or
npm install @datadog/electron-sdk

Initialize

Call init in your main process before creating any browser windows:

import { init } from '@datadog/electron-sdk';

await init({
  clientToken: '<CLIENT_TOKEN>',
  applicationId: '<APPLICATION_ID>',
  service: 'my-electron-app',
  site: 'datadoghq.com',
});

Available Features

• Sessions — Session-based event grouping
• RUM Views — One view per main process instance
• RUM Errors — Capture Node errors and crashes in main process
• Renderer Bridge — Capture RUM events from renderer processes via the browser SDK
• Operation Monitoring (experimental) — Track start / succeed / fail steps of critical user-facing workflows

Operation Monitoring (experimental)

Operation Monitoring lets you track the lifecycle of critical user-facing workflows (login, checkout, file upload, video playback, …) by emitting paired start / end steps. The backend correlates the steps by name (and optional operationKey) and exposes them as a single Operation in the RUM UI.

⚗️ This API is in preview and the signatures may change before stable release.

import { startOperation, succeedOperation, failOperation } from '@datadog/electron-sdk';

// Simple operation
startOperation('checkout');
try {
  await runCheckout();
  succeedOperation('checkout');
} catch (error) {
  failOperation('checkout', 'error');
}

// Parallel operations sharing a name — distinguished by `operationKey`
startOperation('upload', { operationKey: 'profile_pic' });
startOperation('upload', { operationKey: 'cover_photo' });
succeedOperation('upload', { operationKey: 'profile_pic' });
failOperation('upload', 'abandoned', { operationKey: 'cover_photo' });

The renderer process keeps using @datadog/browser-rum directly (with the feature_operation_vital experimental flag enabled on its init). API signatures match exactly, so you can start an operation in one process and complete it in the other — the backend correlates steps by name + operationKey.

Renderer Process Support

In order to monitor the renderer process, the Browser SDK must be setup in pages loaded by the renderer. The Electron SDK exposes a DatadogEventBridge to every renderer process via a preload script. When present, the Browser SDK detects the bridge and routes events through IPC to the Electron SDK instead of sending them directly to Datadog servers.

Unbundled apps

For apps that don't bundle the main process, the SDK automatically registers the preload script. No additional setup is needed.

Bundled apps (Vite, Webpack)

If your main process is bundled (e.g. Electron Forge with the Vite or Webpack plugin), automatic preload injection won't work. Instead, add the following import to your preload script:

// src/preload.ts
import '@datadog/electron-sdk/preload';

This ensures the bridge code is bundled into your app's preload.js and included in the final package.

API

init(config: InitConfiguration): Promise<boolean>

Initialize the SDK. Returns true on success, false if configuration is invalid.

addError(error: unknown, options?: ErrorOptions): void

Report a manually handled error.

import { addError } from '@datadog/electron-sdk';

try {
  riskyOperation();
} catch (error) {
  addError(error, { context: { component: 'sync' } });
}

startOperation(name: string, options?: FeatureOperationOptions): void

Start a RUM Operation step. Pair every startOperation with exactly one succeedOperation or failOperation. Use options.operationKey to distinguish parallel operations sharing the same name.

Note: name is required and should only contain letters, digits, _, ., @, $, -.

succeedOperation(name: string, options?: FeatureOperationOptions): void

Record the successful completion of a RUM Operation. Pass the same name (and operationKey, if any) used to start it.

failOperation(name: string, failureReason: FailureReason, options?: FeatureOperationOptions): void

Record the failure of a RUM Operation. failureReason must be one of 'error' | 'abandoned' | 'other'.

type FailureReason = 'error' | 'abandoned' | 'other';

interface FeatureOperationOptions {
  /** Distinguishes parallel operations sharing the same `name`. */
  operationKey?: string;
  /** Free-form attributes merged into the event's `context`. */
  context?: Record<string, unknown>;
  /** Free-form description attached to `vital.description`. */
  description?: string;
}

Deprecated aliases. The early-preview names startFeatureOperation / succeedFeatureOperation / failFeatureOperation are kept as deprecated aliases for backwards compatibility. They forward to the un-prefixed names above and emit a one-time runtime warning. They will be removed in the next major release — migrate to startOperation / succeedOperation / failOperation.

Configuration Options

Option	Type	Required	Default	Description
clientToken	string	Yes	—	Datadog client token
applicationId	string	Yes	—	RUM application ID
site	string	Yes	—	Datadog site (e.g. datadoghq.com, datadoghq.eu, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ddog-gov.com)
service	string	Yes	—	Service name
env	string	No	—	Application environment
version	string	No	—	Application version
telemetrySampleRate	number	No	20	Telemetry sample rate (0–100)
batchSize	'SMALL' | 'MEDIUM' | 'LARGE'	No	—	Batch size for event uploads
uploadFrequency	'RARE' | 'NORMAL' | 'FREQUENT'	No	—	Upload frequency for event batches
defaultPrivacyLevel	'mask' | 'allow' | 'mask-user-input'	No	'mask'	Default privacy level for renderer session replay
allowedWebViewHosts	string[]	No	[]	Hostnames allowed for the renderer bridge