Electron

@sentry/electron is the official Sentry SDK for Electron applications. It can capture JavaScript exceptions in the main and renderer processes, as well as collect native crash reports (Minidumps).

Install

npm install --save @sentry/electron

Configure

You need to call init in the main process and every renderer process you spawn.

import * as Sentry from "@sentry/electron";

Sentry.init({ dsn: "https://examplePublicKey@o0.ingest.sentry.io/0" });

Once configured, all unhandled exceptions and native crashes are automatically captured by Sentry.

Important: Note your DSN. The DSN (Data Source Name) tells the SDK where to send events. If you forget it, view Settings -> Projects -> Client Keys (DSN) in the Sentry web UI.

Wizard

Our Sentry Wizard can help with the setup process. Make sure you have installed the @sentry/wizard npm package globally, then run:

npm install -g @sentry/wizard
sentry-wizard --integration electron

This will guide you through the installation and configuration process and suggest useful tools for development. If you instead prefer to setup manually, keep reading.

Configuring the Client

Start by configuring the SDK as described above. This will enable the Electron CrashReporter for native app crashes and capture any uncaught JavaScript exceptions using the JavaScript SDKs under the hood. Be sure to call this function as early as possible in the main process and all renderer processes to also catch errors during startup.

If you are using preload scripts, have contextIsolation enabled and want to capture errors from the isolated preload context, you should call init early in that context too.

App userData Directory

If you change the userData directory used by your app, ensure this change is made before you configure the SDK as this path is used to cache scope and events between application restarts.

import { app } from "electron";
import * as Sentry from "@sentry/electron";

app.setPath("userData", "~/.config/my-app");
Sentry.init({ dsn: "https://examplePublicKey@o0.ingest.sentry.io/0" });

Bundler Configuration

The SDK attempts to ensure JavaScript bundlers pick up the correct entry point for the Electron process type, but this is not foolproof. If the incorrect entry point is selected, your bundler may throw an error or an error will be thrown at runtime. If this occurs there are process specific exports to ensure that the correct code is bundled for the process.

In the main process:

import * as Sentry from "@sentry/electron/main";

In the renderer processes:

import * as Sentry from "@sentry/electron/renderer";

Framework-Specific SDKs

If you're using a framework-specific Sentry SDK in the Electron renderers, you can pass that init function as the second parameter and the two SDKs functionalities will be combined:

import { init } from "@sentry/electron/renderer";
import { init as reactInit } from "@sentry/react";

init(
  {
    /* config */
  },
  reactInit
);

Offline Support

The default transport automatically handles offline events caching from both the main and renderer processes. Following, are a number of options that allow you to customize queueing behavior:

import * as Sentry from "@sentry/electron/main";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  transportOptions: {
    // The maximum number of days to keep an event in the queue.
    maxQueueAgeDays: 30,
    // The maximum number of events to keep in the queue.
    maxQueueCount: 30,
    // Called every time the number of requests in the queue changes.
    queuedLengthChanged: (length) => {},
    // Called before attempting to send an event to Sentry. Used to override queuing behavior.
    //
    // Return 'send' to attempt to send the event.
    // Return 'queue' to queue and persist the event for sending later.
    // Return 'drop' to drop the event.
    beforeSend: (request) => (isOnline() ? "send" : "queue"),
  },
});

Inter-Process Communication

To give the most detailed context for all events including native crashes, the SDK merges context, scope and breadcrumbs from all processes in the Electron main process.

By default, the SDK attempts to establish communication from renderer to main via Electron IPC API's and if that fails, falls back to using a custom HTTP protocol. You can change this default via the ipcMode option which can be one of Classic, Protocol or Both.

const { init, IPCMode } = require("@sentry/electron");

init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  debug: true,
  ipcMode: IPCMode.Protocol,
});

Preload Injection

The SDK attempts to inject a preload script via session.setPreloads(preloads) and by default only does this for the defaultSession. If you are using other sessions, you can pass custom sessions via the getSessions option in the main process:

import { session } from "electron";
import * as Sentry from "@sentry/electron/main";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  getSessions: () => [
    session.defaultSession,
    session.fromPartition("persist:my-session"),
  ],
});

If your app bundles the main process JavaScript, the SDK cannot automatically inject preload scripts because the script will be missing from the packaged app. In this case, the SDK will send events and scope updates via a custom HTTP protocol and window.fetch.

Manual Preload

If you would like to manually bundle and configure the preload script, you should import the SDK preload code into your own preload script:

import "@sentry/electron/preload";

This script exposes IPC to the isolated renderer via Electrons contextBridge API.

Check out the example apps for how to do this.

Debug Information

To get symbolicated stack traces for native crashes, you should enable fetching debug symbols from the Electron symbol server. Go to Project Settings > Debug Files and add Electron to the list of built-in repositories.

If your app uses a custom Electron fork, contains modules with native extensions or spawns subprocesses, you should upload those symbols manually using the Sentry CLI. For more information, see Native Usage.

Dealing with Minified Source Code

The Electron SDK supports Source Maps. If you upload source maps in addition to your minified files that data becomes available in Sentry. For more information see Source Maps.

Native

Sentry can process Minidumps created when any of the Electron processes crash. To do so, the SDK needs to upload those files once the application restarts (or immediately for renderer crashes). All event meta data including user information and breadcrumbs are included in these uploads.

Due to restrictions of macOS app sandboxing, native crashes cannot be collected in Mac App Store builds. In this case, native crash handling will be disabled.

Providing Debug Information

To allow Sentry to fully process native crashes and provide you with symbolicated stack traces, you need to upload Debug Information Files (sometimes also referred to as Debug Symbols or just Symbols).

First, make sure that the Electron Symbol Server is enabled for your project. Go to Project Settings > Debug Files and choose Electron from the list of Builtin Repositories. You can add more symbol servers for the platforms you are deploying to, depending on your needs.

If your application contains custom native extensions or you wish to symbolicate crashes from a spawned child process, upload their debug information manually during your build or release process. See Debug Information Files for a detailed description of how to set up Sentry for native development. Additionally, see Uploading Debug Information for the upload process.

Child Processes

The SDK relies on the Electron CrashReporter to generate the crash dumps. To receive crash reports for child processes, you need to make sure the crash reporter is activated by either the SDK or manually (see below).

An exception to this is macOS, where the crash reporter only needs to be started in the main process and watches all its child processes. The SDK already takes care of this difference, so there is no need to manually disable enableNative.

For custom child processes, especially ones not written in JavaScript, you need to integrate a library that can generate Minidumps. These are most notably Crashpad and Breakpad. Please refer to their respective documentation on how to build and integrate them. Configure them with the following upload URL:

https://o0.ingest.sentry.io/api/0/minidump/?sentry_key=examplePublicKey

It currently not possible create breadcrumbs or other event meta data from native code. This has to happen in JavaScript. Support for this is planned in future releases.

Manual Crash Reporting

You can also capture native crashes by starting the Electron CrashReporter manually. Sentry is able to provide symbolicated stack traces and show system information, but no Electron-specific metadata, breadcrumbs or context information will be present. This is useful in cases where you cannot use the full Electron SDK:

const { crashReporter } = require("electron");
crashReporter.start({
  companyName: "YourCompany",
  productName: "YourApp",
  ignoreSystemCrashHandler: true,
  submitURL: "https://o0.ingest.sentry.io/api/0/minidump/?sentry_key=examplePublicKey",
});

Source Maps

To find out why Sentry needs your source maps and how to provide them visit: Source Maps