Electron SDK v3 Proposal

[timfish]

The current SDK has a single entry point which should be called in the main, preload and renderer processes. This can make getting started simple but also:

• Complicates the code significantly
• Causes issues with bundling
  • You need to add electron to externals
  • webpack electron-preload target uses the wrong import
• Complicates using differing integrations for different processes

I am proposing refactoring the SDK to be thinner layers on top of the node/browser SDKs. The Electron specific functionality and optional features would then be added as integrations. This will give the greatest flexibility and allow SDK users to pick and choose which feature they would like.

Main Process

Accessible via:

import { init } from `@sentry/electron`;
// or more specific with better types
import { init } from `@sentry/electron/main`;

@sentry/node with ElectronNetTransport and the following integrations:

• ElectronBreadcrumbs (default)- Adds breadcrumbs for Electron events
• OnUncaughtException (default) - Electron specific uncaughtException handling
• MainContext (default) - Adds OS/platform context to events
• AdditionalContext (default) - Includes addition device context like screen resolution, CPU/memory info
• MainProcessSession (default when options.autoSessionTracking !== false) - Tracks sessions as the main process lifetime
• SentryMinidump (default) - Sends minidumps via Sentry Envelope endpoint with full context/breadcrumbs
• ElectronMinidump - Sends minidumps via Electron built in uploader with partial context
• PreloadInjection (default) - Automatically injects preload script via session.addPreloads() api
• ChildProcess (default) - Includes breadcrumbs for events with Electrons sub processes

Preload

Accessible via:

import `@sentry/electron/preload`;

The preload is simply a 10-20 line script that:

• Exposes IPC to the main process
  • Uses contextBridge when enabled
• Calls crashReporter.start() for older Electron versions where this is still required in the renderer

By default, the PreloadInjection integration will attempt to inject preload scripts where possible. This will not work when the main process but the SDK will fall back to sending events and scope to the main process via a custom protocol and fetch

Renderer Process

Accessible via:

import { init } from `@sentry/electron`;
// or more specific with better types
import { init } from `@sentry/electron/renderer`;

@sentry/browser with the following integrations:

• ScopeToMain (default) - Sends scope updates to the main process to be merged and give more detail with minidumps
• EventToMain (default) - Sends events via the main process

Usage

With all the default integrations and for non-bundled usage, the instructions will remain much the same.
Call init in the main and renderer processes:

sentry.js

const { init } = require('@sentry/electron');

init({
  dsn: '__DSN__'
});

main.js and renderer.js

// First thing in both processes...
require('./sentry');

Complex configurations

By using @sentry/electron/renderer or @sentry/electron/main you gain access to the configuration, type definitions and integrations for the specific process type.

Browser Tracing

renderer.js

import { init } from '@sentry/electron/renderer';
import { Integrations } from '@sentry/tracing';

init({
  dsn: "__DSN__",
  integrations: [new Integrations.BrowserTracing()],
  tracesSampleRate: 1.0,
});

Disabling minidumps

In the main process, remove the SentryMinidump integration

Using the Electron minidump uploader

In the main process, add the ElectronMinidump integration and the SDK automatically removes the SentryMinidump integration.

[damienallen]

Really relieved to see your PR in the pipeline.

We run a couple of electron apps and can't help but notice it falling behind (i.e. really missing sessions). Many thanks for the refactor!

[timfish]

This is now available for testing under the next tag on npm!

[timfish]

This has been released as 3.0.0!