Electron SDK v3 changes

src/includes/getting-started-config/javascript.electron.mdx

@@ -1,4 +1,4 @@
-You need to call `init` in your `main` and every `renderer` process you spawn.
+You need to call `init` in the `main` process and every `renderer` process you spawn.
 
 ```javascript
 import * as Sentry from "@sentry/electron";

src/includes/getting-started-install/javascript.electron.mdx

@@ -1,5 +1,3 @@
-If you are using `yarn` or `npm` you can add our package as a dependency:
-
 ```bash
 # Using yarn
 yarn add @sentry/electron

src/includes/getting-started-verify/javascript.electron.mdx

@@ -8,3 +8,11 @@ myUndefinedFunction();
 
 You may want to try inserting this into both your `main` and any `renderer`
 processes to verify Sentry is operational in both.
+
+You can verify that native crash reporting is working by triggering a crash in the current process:
+
+```javascript
+process.crash();
+```
+
+Note: Native crashes in the Electron `main` process are not sent until the app is run again.

src/includes/performance/configure-sample-rate/javascript.electron.mdx

@@ -0,0 +1,24 @@
+```javascript
+// BrowserTracing should only be configured in Electron renderer processes
+import * as Sentry from "@sentry/electron/renderer";
+
+// If taking advantage of automatic instrumentation (highly recommended)
+import { BrowserTracing } from "@sentry/tracing";
+// Or, if only manually tracing
+// import * as _ from "@sentry/tracing"
+// Note: You MUST import the package in some way for tracing to work
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+
+  // This enables automatic instrumentation (highly recommended), but is not
+  // necessary for purely manual usage
+  integrations: [new BrowserTracing()],
+
+  // To set a uniform sample rate
+  tracesSampleRate: 0.2
+
+  // Alternatively, to control sampling dynamically
+  tracesSampler: samplingContext => { ... }
+});
+```

src/includes/performance/enable-automatic-instrumentation/javascript.electron.mdx

@@ -0,0 +1,24 @@
+To enable tracing, include the `BrowserTracing` integration in your SDK configuration options. (Note that when using ESM modules, the main `@sentry/*` import must come before the `@sentry/tracing` import.)
+
+After configuration, you will see both `pageload` and `navigation` transactions in the Sentry UI.
+
+```javascript
+// BrowserTracing should only be configured in Electron renderer processes
+import * as Sentry from "@sentry/electron/renderer";
+import { BrowserTracing } from "@sentry/tracing"; // Must import second
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+
+  integrations: [
+    new BrowserTracing({
+      tracingOrigins: ["localhost", "my-site-url.com", /^\//],
+      // ... other options
+    }),
+  ],
+
+  // We recommend adjusting this value in production, or using tracesSampler
+  // for finer control
+  tracesSampleRate: 1.0,
+});
+```

src/includes/set-environment/javascript.electron.mdx

@@ -2,6 +2,6 @@
 import * as Sentry from "@sentry/electron";
 
 Sentry.init({
-  environment: "production",
+  environment: "insiders",
 });
 ```

src/platforms/common/configuration/releases.mdx

@@ -4,7 +4,6 @@ sidebar_order: 2
 description: "Learn how to configure your SDK to tell Sentry about your releases."
 notSupported:
   - perl
-  - javascript.electron
 ---
 
 <PlatformSection supported={["unity"]}>

src/platforms/common/enriching-events/transaction-name.mdx

@@ -10,7 +10,6 @@ supported:
 notSupported:
   - javascript.cordova
   - javascript.nextjs
-  - javascript.electron
   - native.minidumps
   - native.ue4
 description: "Learn how to set or override the transaction name to capture the user and gain critical pieces of information that construct a unique identity in Sentry."

src/platforms/common/performance/index.mdx

@@ -22,7 +22,6 @@ supported:
   - php
 notSupported:
   - javascript.cordova
-  - javascript.electron
   - native.breakpad
   - native.crashpad
   - native.minidumps

src/platforms/common/performance/instrumentation/index.mdx

@@ -4,7 +4,6 @@ sidebar_order: 20
 description: "Learn how to instrument performance in your app."
 notSupported:
   - javascript.cordova
-  - javascript.electron
   - node
   - native.breakpad
   - native.crashpad

src/platforms/javascript/common/configuration/integrations/rrweb.mdx

@@ -4,6 +4,8 @@ sidebar_order: 100
 description: "Enable session replay attachments using rrweb."
 redirect_from:
   - /platforms/javascript/integrations/rrweb/
+notSupported:
+  - javascript.electron
 ---
 
 Sentry provides a proof-of-concept integration with [rrweb](https://www.rrweb.io/) - a toolkit for recording and replaying user sessions. This can be extremely helpful when diagnosing complex user behavior in a rich Single Page Application.

src/platforms/javascript/guides/electron/configuration/environments.mdx

@@ -0,0 +1,15 @@
+---
+title: Environments
+sidebar_order: 5
+description: "Learn how to configure your SDK to tell Sentry about your environments."
+---
+
+Sentry automatically creates environments when it receives an event with the environment tag. Environments are case sensitive. The environment name can't contain newlines, spaces or forward slashes, can't be the string "None", or exceed 64 characters. You can't delete environments, but you can [hide](/product/sentry-basics/environments/#hidden-environments) them.
+
+The Electron SDK automatically sets the `environment` to `development` or `production` depending on whether the application is packaged.
+
+You can override this default for other environments:
+
+<PlatformContent includePath="set-environment" />
+
+Environments help you better filter issues, releases, and user feedback in the Issue Details page of sentry.io, which you learn more about in our [documentation that covers using environments](/product/sentry-basics/environments/).

src/platforms/javascript/guides/electron/configuration/integrations/default.mdx

@@ -0,0 +1,225 @@
+---
+title: Default Integrations
+excerpt: ""
+description: "Learn more about the integrations that are enabled by default."
+---
+
+The Sentry Electron SDK uses `@sentry/node` in the main process and `@sentry/browser` in the renderers.
+
+A number of integrations are included by default that setup communication between Electrons multiple processes and include Electron specific context and breadcrumbs.
+
+## Main Process
+
+### `MainContext`
+
+Adds app, operating system and runtime context to all events.
+
+### `OnUncaughtException`
+
+Supports capturing events from `uncaughtException` while retaining Electrons default behaviour of displaying an error dialog if there are no other listeners.
+
+To disable Electrons default error dialog, simply add another listener:
+
+```javascript
+process.on("uncaughtException", () => {});
+```
+
+### `ElectronBreadcrumbs`
+
+Captures breadcrumbs for events for many of Electrons built-in modules. The breadcrumbs captured for each module can be configured `true` to capture all events or `false` to capture no events. Alternatively you can supply a function which is passed the event name and returns `true` or `false` depending on whether the event should be captured.
+
+The defaults for this integration are effectively:
+
+```javascript
+import * as Sentry from "@sentry/electron";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    Sentry.Integrations.ElectronBreadcrumbs({
+      app: name => !name.startsWith("remote-"),
+      autoUpdater: true,
+      webContents: name =>
+        ["dom-ready", "context-menu", "load-url", "destroyed"].includes(name),
+      browserWindow: name =>
+        [
+          "closed",
+          "close",
+          "unresponsive",
+          "responsive",
+          "show",
+          "blur",
+          "focus",
+          "hide",
+          "maximize",
+          "minimize",
+          "restore",
+          "enter-full-screen",
+          "leave-full-screen",
+        ].includes(name),
+      screen: true,
+      powerMonitor: true,
+    }),
+  ],
+});
+```
+
+### `SentryMinidump`
+
+Captures minidumps and sends them with full context to the Sentry Envelope endpoint using a custom uploader.
+
+### `PreloadInjection`
+
+Injects a preload script via the Electron [`session.setPreloads(preloads)`](https://www.electronjs.org/docs/latest/api/session#sessetpreloadspreloads) API. By default sessions are only injected into the `defaultSession`. If you are using other sessions, you can pass a function as `getSessions` to `init`.
+
+```javascript
+import { session } from "electron";
+import * as Sentry from "@sentry/electron";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  getSessions: () => [
+    session.defaultSession,
+    session.fromPartition("persist:my-session"),
+  ],
+});
+```
+
+### `AdditionalContext`
+
+Adds additional device context to events.
+
+The constructor takes a number of options which all default to `true`:
+
+```typescript
+interface AdditionalContextOptions {
+  cpu: boolean;
+  screen: boolean;
+  memory: boolean;
+  language: boolean;
+}
+```
+
+To disable specific context items, set them as `false`:
+
+```javascript
+import * as Sentry from "@sentry/electron";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    Sentry.Integrations.AdditionalContext({
+      screen: false,
+    }),
+  ],
+});
+```
+
+### `Net`
+
+Captures breadcrumbs and tracing spans for Electrons `net` module. By default breadcrumbs and tracing spans are enabled and `sentry-trace` headers are added to requests for all origins.
+
+The integration can be configured via constructor options:
+
+```typescript
+interface NetOptions {
+  /**
+   * Whether breadcrumbs should be captured for net requests
+   *
+   * Defaults to: true
+   */
+  breadcrumbs: boolean;
+  /**
+   * Whether to capture transaction spans for net requests
+   *
+   * Defaults to: true
+   */
+  tracing: boolean | (method: string, url: string) => boolean;
+  /**
+   * Whether to add 'sentry-trace' headers to outgoing requests
+   *
+   * Defaults to: true
+   */
+  tracingOrigins: boolean | (method: string, url: string) => boolean;
+}
+```
+
+For example, to disable breadcrumb capture and addition of `sentry-trace` headers and only capture spans for `POST` requests:
+
+```javascript
+import * as Sentry from "@sentry/electron";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    Sentry.Integrations.Net({
+      breadcrumbs: false,
+      tracing: method => method == "POST",
+      tracingOrigins: false,
+    }),
+  ],
+});
+```
+
+### `ChildProcess`
+
+Captures breadcrumbs and events for child process exits and crashes.
+
+```typescript
+type ExitReason =
+  | "clean-exit"
+  | "abnormal-exit"
+  | "killed"
+  | "crashed"
+  | "oom"
+  | "launch-failed"
+  | "integrity-failure";
+
+interface ChildProcessOptions {
+  /** Child process events that generate Sentry breadcrumbs */
+  breadcrumbs: ExitReason[];
+  /** Child process events that generate Sentry events */
+  events: ExitReason[];
+}
+```
+
+For example, to disable capture of breadcrumbs and only capture events for Out-Of-Memory crashes:
+
+```javascript
+import * as Sentry from "@sentry/electron";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    Sentry.Integrations.ChildProcess({
+      breadcrumbs: [],
+      capture: ["oom"],
+    }),
+  ],
+});
+```
+
+### `MainProcessSession`
+
+Captures sessions linked to the lifetime of the Electron main process. These sessions result in [Release Health](/product/releases/health/) statistics being displayed in Sentry.
+
+Unless `autoSessionTracking` is set to `false`, this integration will be automatically added.
+
+```javascript
+import * as Sentry from "@sentry/electron";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  autoSessionTracking: false,
+});
+```
+
+## Renderer Process
+
+### `ScopeToMain`
+
+Captures scope updates and breadcrumbs in renderer processes and forwards them to the Electron main process.
+
+### `EventToMain`
+
+Captures events in the renderer processes and forwards them to the Electron main process. This integration prevents events from being sent by the underlying `@sentry/browser` SDK.

src/platforms/javascript/guides/electron/configuration/integrations/optional.mdx

@@ -0,0 +1,19 @@
+---
+title: Optional Integrations
+description: "Learn more about optional integrations."
+---
+
+### `ElectronMinidump`
+
+Captures and sends minidumps via Electrons built in `crashReporter` uploader. Renderer and GPU crashes will only include minimal context. For full context, you should prefer the default `SentryMinidump` integration.
+
+If you add the `ElectronMinidump` integration, the `SentryMinidump` integration will be automatically removed to avoid duplicate crashes being reported.
+
+```javascript
+import * as Sentry from "@sentry/electron";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [Sentry.Integrations.ElectronMinidump()],
+});
+```