DOCSEARCHbyAlgolia
Submit Docs

Sentry Electron SDK

repository·master·Indexed 42 days ago

https://github.com/getsentry/sentry-electron

Official Sentry SDK for Electron (v7.19.0) providing full-stack error monitoring across main and renderer processes, including native crash reporting via Minidumps. Supports Electron >= v23 and integrates Node.js and browser error capturing with unified context and breadcrumbs.

Tokens
11.2K
Snippets
33
Records
43
Agent score
53%

What's inside Sentry Electron

  1. Features of the Sentry Electron SDK

    master

    The Sentry Electron SDK provides comprehensive error monitoring for Electron applications by combining several capabilities:

    • Node errors: Captures errors in the main process using @sentry/node.
    • JavaScript errors: Captures errors in renderer processes using @sentry/browser.
    • Native crashes: Captures Minidump crash reports from both renderers and the main process.
    • Unified Context: Collects breadcrumbs and context information across both the main process and all renderers.
    • Compatibility: Supports electron >= v23.

  2. Upgrade from 4.x to 5.x

    master

    Upgrading to v5 introduces significant changes to how the SDK is imported and how integrations are defined.

    Supported Electron Versions:

    • Electron >= 15.0.0 (due to Node.js >= 14.18.0 requirement).

    Key Changes:

    • Import Strategy: The root export @sentry/electron is no longer supported and will throw an error. You must import from process-specific entry points.
    • Functional Integrations: Integrations are no longer classes; they are now functions. Using new Integrations.X() is deprecated.
    • Offline Transport: The beforeSend callback is replaced by shouldSend and shouldStore callbacks to align with @sentry/core specifications.
    • Tags: The event_type tag was removed in favor of event.environment.

  3. Use relative imports for specific Electron processes (v3+)

    master

    To support complex configurations or specific bundler requirements, you can skip automatic detection and import the process-specific entry point directly.

    // Main Process
const Sentry = require('@sentry/electron/main');
// or
import * as Sentry from '@sentry/electron/main';

// Renderer Process
const Sentry = require('@sentry/electron/renderer');
// or
import * as Sentry from '@sentry/electron/renderer';

// Preload Code
require('@sentry/electron/preload');
// or
import '@sentry/electron/preload';

  4. Upgrade from 5.x to 6.x

    master

    Upgrading to v6 includes changes to how session tracking is handled and how PII is managed.

    Supported Electron Versions:

    • Electron >= 23.0.0 (due to Node.js >= 18.0.0 requirement).

    Key Changes:

    • Session Tracking: The autoSessionTracking option was removed. To disable session tracking, you must now filter out the MainProcessSession integration from the integrations array.
    • Breadcrumbs: processThreadBreadcrumbIntegration was removed; its functionality is now part of childProcessIntegration.
    • IP Addresses: User IP addresses are only included if sendDefaultPii is set to true.
    // Disabling session tracking in v6
import * as Sentry from "@sentry/electron/main";

Sentry.init({
  dsn: "__DSN__",
  integrations: (defaults) =>
    defaults.filter((i) => i.name !== "MainProcessSession"),
});

// Including IP addresses
Sentry.init({
  dsn: "__DSN__",
  sendDefaultPii: true,
});

  5. Initialize Sentry in different Electron processes (v5+)

    master

    In v5 and later, you must import the specific entry point for the process you are working in to ensure proper tree-shaking and bundler compatibility.

    • Main Process: Import from @sentry/electron/main.
    • Renderer Process: Import from @sentry/electron/renderer. Note that much of the configuration is inherited from the main process, so Sentry.init() often requires no arguments.
    // In the Electron main process
import * as Sentry from '@sentry/electron/main';
Sentry.init({
  dsn: '__DSN__',
});

// In the Electron renderer processes
import * as Sentry from '@sentry/electron/renderer';
Sentry.init();

  6. Upgrade from 2.x to 3.x

    master

    v3 introduced significant changes to simplify usage and improve bundler support.

    Key Features:

    • Session Tracking: Enabled by default via MainProcessSession. Opt out using autoSessionTracking: false.
    • Relative Imports: You can now import process-specific code directly (@sentry/electron/main, @sentry/electron/renderer, or @sentry/electron/preload) to bypass automatic detection.
    • Offline Support: ElectronOfflineNetTransport is now the default.
    • Preload Scripts: No longer required for Electron >= v5 in most scenarios.
    • Browser Tracing: Supports performance monitoring in the renderer process using @sentry/tracing.

    Major Breaking Changes:

    • Native crashes now respect sampleRate and beforeSend.
    • Configuration is now handled through integrations rather than top-level options.

  8. Initialize the Sentry Electron SDK

    master

    To use the Sentry Electron SDK, you must call init(options) as early as possible in the entry modules of your main process and all renderer processes (or any sub-processes you spawn). This initializes the SDK and hooks the environment for error capturing.

    Main Process

    In the main process, import init from @sentry/electron/main and provide your DSN.

    Renderer Processes

    In renderer processes, import init from @sentry/electron/renderer.

    Using with Framework SDKs (e.g., React)

    If you are using a framework-specific SDK (like @sentry/react), you can combine their functionalities by passing the framework's init function as the second argument to the Electron renderer init function.

    // In the Electron main process
import { init } from '@sentry/electron/main';

init({
  dsn: '__DSN__',
  // ...
});

// In the Electron renderer processes
import { init } from '@sentry/electron/renderer';

init();

// Combining with a framework SDK like React
import { init } from '@sentry/electron/renderer';
import { init as reactInit } from '@sentry/react';

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

  9. Configure Native Crash Reporting

    master

    You can choose between three modes for native crash reporting by managing the integrations array in init():

    1. SentryMinidump (Default): Uploads minidump files via the Sentry Envelope endpoint with full breadcrumbs and context.
    2. ElectronMinidump: Uploads minidumps via the built-in Crashpad/Breakpad uploader with partial context. To use this, prepend it to the defaultIntegrations list.
    3. No Native Crash Reporting: To disable native crash reporting entirely, filter out the SentryMinidump integration from the defaultIntegrations list.
    import { init, Integrations } from '@sentry/electron';

// Option 2: Use ElectronMinidump integration
init({
  dsn: '__DSN__',
  integrations: (defaultIntegrations) => {
    return [new Integrations.ElectronMinidump(), ...defaultIntegrations];
  },
});

// Option 3: Disable native crash reporting
init({
  dsn: '__DSN__',
  integrations: defaultIntegrations => {
    return defaultIntegrations.filter(i => i.name != Integrations.SentryMinidump.Id);
  }
});

  10. Use childProcessIntegration to monitor Electron processes

    master

    The childProcessIntegration monitors both child-process-gone and render-process-gone events in Electron.

    • Child Processes: Captures events from spawned processes via the child-process-gone event. It includes metadata like serviceName and name in the logs/breadcrumbs.
    • Render Processes: Captures events from renderer processes via the render-process-gone event. If the Sentry client is configured with a getRendererName function in its options, that name will be used instead of the default 'renderer'.

  11. Customize Electron event filtering

    master

    When configuring electronBreadcrumbsIntegration, you can control the verbosity of breadcrumbs using different types of filters for the following categories: app, autoUpdater, webContents, browserWindow, screen, and powerMonitor.

    Supported filter types:

    • Boolean: true captures all events in that category; false captures none.
    • String Array: An array of specific event names (e.g., ['show', 'hide']) will only trigger breadcrumbs for those exact events.
    • Function: A predicate function (name: string) => boolean allows for complex filtering logic (e.g., excluding specific patterns).

  12. Configure IPC communication modes

    master

    The IPCMode enum defines how the Sentry SDK communicates between the Electron renderer and main processes. You can choose between different modes depending on your Electron configuration:

    • Classic: Uses standard Electron IPC to receive messages from renderers.
    • Protocol: Uses the Electron protocol module to receive messages.
    • Both: Configures both methods for maximum compatibility. This is recommended as renderers will favor IPC but fall back to the protocol if IPC has not been configured in a preload script.
    export enum IPCMode {
  Classic = 1,
  Protocol = 2,
  Both = 3,
}