Integrate an Electron application-Cloud Monitor(CMS)-阿里云帮助中心

Integrate the @arms/rum-electron SDK to automatically collect performance metrics, exceptions, crashes, and user behavior from your Electron desktop application and report the data to the ARMS console. The SDK uses a dual-process architecture: the main process collects crash and exception data and handles reporting, while the renderer process collects PV, performance, Web Vitals, and API request data. All data is sent to the main process via an IPC channel for centralized reporting, with no changes required to your renderer process code.

Prerequisites

Electron >= 28.0.0
Node.js >= 16
ARMS user experience monitoring is activated.

Create an application

Log on to the ARMS console.
In the left-side navigation pane, choose User Experience Monitoring > Application List. In the top menu bar, select the target region.
On the Application List page, click Add Application.
In the Create Application panel, click Electron.
In the Electron panel, enter an application name and description, and then click Create.

Note: The application name must be unique. After the application is created, an endpoint is automatically generated for it.
Save the generated endpoint. You will need it to initialize the SDK.

Install the SDK

Run the following command in the root directory of your Electron project to install the SDK:

npm install @arms/rum-electron

Note: electron is a peer dependency of the SDK and requires version 28.0.0 or later. If electron is not already installed in your project, you must install it as well.

Initialize the SDK

In your main process entry file (for example, main.ts), call init() before the app.ready event fires:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',  // Replace with the endpoint obtained from the console
  env: 'prod',                  // Environment: 'prod' | 'gray' | 'pre' | 'daily' | 'local'
  version: '1.0.0',             // Application version
});

Important

The init() method must be called before Electron's app.ready event fires. The SDK needs to register a custom protocol (rum-event://) and a preload script early in the application startup. These operations must be completed before the app.ready event to ensure the SDK functions correctly.

After initialization, the SDK behaves as follows by default:

The autoInject parameter is true by default. The SDK automatically injects the Browser SDK into the renderer process of each BrowserWindow.
You do not need to modify the renderer process code or add a preload script.
Data is sent via an IPC channel to the main process for centralized reporting.

Verify the integration

After initialization, start your Electron application and perform some actions such as switching pages or making network requests. Use the beforeReport callback to view reported data in the main process console:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  beforeReport(bundle) {
    console.log('[RUM] Reporting data:', bundle);
    return bundle;
  },
});

Wait one to two minutes, then navigate to User Experience Monitoring > Application List in the ARMS console. Select your application and verify that data is being reported.

The console provides the following information:

Real-time overview: Core metrics such as PV, UV, JS error count, and API request count.
Session details: User session journeys and page navigation paths.
Exception analysis: JavaScript error stack traces, crash analysis, and error distribution.
Performance analysis: API latency distribution and a list of the slowest APIs.

Advanced usage

Manual injection mode

To prevent the SDK from automatically injecting the Browser SDK into all renderer processes, set autoInject: false and manually initialize the SDK in the renderer processes that you want to monitor.

Main process initialization:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  autoInject: false,  // Disable automatic injection
});

Renderer process manual initialization:

import armsRum from '@arms/rum-electron/browser';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
});

In manual injection mode, data is collected only from renderer processes where you explicitly initialize the SDK using @arms/rum-electron/browser. This mode is ideal for scenarios requiring fine-grained control over the monitoring scope.

Custom partitions

If your BrowserWindow uses a custom partition configuration, you must ensure the SDK registers a preload script for that partition. The SDK provides two ways to support custom partitions:

Method 1: Configure the partition during initialization

Pass the partition parameter during initialization. The SDK automatically registers the preload script for the specified partition:

import armsRum from '@arms/rum-electron';
import { BrowserWindow } from 'electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  partition: 'persist:main',  // Must match the BrowserWindow partition
});

const win = new BrowserWindow({
  webPreferences: {
    partition: 'persist:main',  // Must match the partition in init()
  },
});

Method 2: Register dynamically after initialization

After initializing the SDK, you can dynamically register a preload script for another partition with registerSession():

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
}).then(() => {
  // Dynamically register for another partition
  armsRum.registerSession('persist:other');
});

Call registerSession() before creating the corresponding BrowserWindow to ensure the change takes effect on the initial page load.

SPA route tracking

If your Electron renderer processes use single-page application (SPA) routing, enable SPA route tracking to automatically collect route change events:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  spaMode: true,  // Or 'hash' / 'history'
});

The spaMode parameter supports the following values:

false: Disables SPA route tracking (default behavior). It only tracks full page loads.
true or 'auto': Automatically detects the routing mode, prioritizing hash-based routing over pathname-based routing.
'hash': Hash routing mode (for example, React HashRouter).
'history': History API routing mode (for example, React BrowserRouter).

Tracing

Configure the tracing object to enable distributed tracing and correlate front-end requests with back-end services:

import armsRum from '@arms/rum-electron';

armsRum.init({
  endpoint: '<YOUR-ENDPOINT>',
  tracing: {
    enable: true,
    sample: 0.1,              // 10% sampling rate
    propagatorTypes: ['tracecontext', 'b3'],  // Trace propagator
    allowedUrls: [
      { match: 'https://api.example.com', sample: 0.5 },  // Track only specified URLs with a 50% sampling rate
    ],
  },
});

The propagatorTypes parameter supports tracecontext, b3, b3multi, and jaeger. The allowedUrls parameter specifies which request URLs to trace. If this parameter is not configured, all requests are traced.