diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index 61146c9ff4cba..cb40f212711ca 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -171,7 +171,9 @@ Set this option to `false` to disable sending of client reports. Client reports Set this option to `true` to add stack local variables to stack traces. + For more advanced configuration options, see the documentation on the Local Variables integration options. + @@ -242,6 +244,21 @@ Options used to configure the transport. This is an object with the following po + +**Options for Electron offline support:** + +The Electron SDK provides built-in offline support that queues events when the app is offline and automatically sends them once the connection is restored. These options let you configure that behavior: + +- `maxAgeDays`: The maximum number of envelopes to keep in the queue. +- `maxQueueSize`: The maximum number of days to keep an envelope in the queue. +- `flushAtStartup`: Whether the offline store should flush shortly after application startup. Defaults to `false`. +- `shouldSend`: Called before the SDK attempts to send an envelope to Sentry. If this function returns false, `shouldStore` will be called to determine if the envelope should be stored. Defaults to `() => true`. +- `shouldStore`: Called before an event is stored. Return `false` to drop the envelope rather than store it. Defaults to `() => true`. + +Check out the [Offline Support](/platforms/javascript/guides/electron/features/offline-support/) documentation for a complete example. + + + @@ -450,27 +467,31 @@ If a root span matches any of the specified patterns, the entire local trace wil By default, no spans are ignored. Here are some predefined matches for common spans to get you started: + ```javascript Sentry.init({ ignoreSpans: [ // Browser connection events - {op: /^browser\.(cache|connect|DNS)$/}, + { op: /^browser\.(cache|connect|DNS)$/ }, // Fonts - {op: 'resource.other', name: /.+\.(woff2|woff|ttf|eot)$/}, + { op: "resource.other", name: /.+\.(woff2|woff|ttf|eot)$/ }, // CSS files - {op: 'resource.link', name: /.+\.css.*$/}, + { op: "resource.link", name: /.+\.css.*$/ }, // JS files - {op: /resource\.(link|script)/, name: /.+\.js.*$/}, + { op: /resource\.(link|script)/, name: /.+\.js.*$/ }, // Images - {op: /resource\.(other|img)/, name: /.+\.(png|svg|jpe?g|gif|bmp|tiff?|webp|avif|heic?|ico).*$/}, + { + op: /resource\.(other|img)/, + name: /.+\.(png|svg|jpe?g|gif|bmp|tiff?|webp|avif|heic?|ico).*$/, + }, // Measure spans - {op: 'measure'}, - ] + { op: "measure" }, + ], }); ``` diff --git a/docs/platforms/javascript/guides/electron/features/index.mdx b/docs/platforms/javascript/guides/electron/features/index.mdx new file mode 100644 index 0000000000000..719d9c74f81cd --- /dev/null +++ b/docs/platforms/javascript/guides/electron/features/index.mdx @@ -0,0 +1,9 @@ +--- +title: Electron Features +description: "Learn how Sentry's Electron SDK exposes features for first class integration with Electron." +excerpt: "" +--- + +The Sentry Electron SDK offers Electron-specific features for first class integration with the framework. + + diff --git a/docs/platforms/javascript/guides/electron/features/inter-process-communication.mdx b/docs/platforms/javascript/guides/electron/features/inter-process-communication.mdx new file mode 100644 index 0000000000000..6f95923dda7ee --- /dev/null +++ b/docs/platforms/javascript/guides/electron/features/inter-process-communication.mdx @@ -0,0 +1,95 @@ +--- +title: Inter-Process Communication +description: "Learn how the Sentry Electron SDK communicates across processes to capture detailed error data." +--- + +To provide the most detailed context for all events, including native crashes, the SDK merges context, scope, and breadcrumbs from all processes into the Electron `main` process. + +By default, the SDK attempts to establish communication from `renderer` to `main` using Electron's IPC APIs. If that fails, it falls back to a custom HTTP protocol. You can change this behavior using the `ipcMode` option: + +```javascript +const { init, IPCMode } = require("@sentry/electron/main"); + +init({ + dsn: "___PUBLIC_DSN___", + debug: true, + ipcMode: IPCMode.Protocol, // Options: IPCMode.Classic, IPCMode.Protocol, or IPCMode.Both +}); +``` + +## Custom IPC Namespace + +If your application uses multiple IPC channels, you can specify a custom namespace to prevent conflicts with Sentry's IPC channels. + +Configure the same namespace across all three contexts: + +**Main process** + +```javascript +import * as Sentry from "@sentry/electron/main"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + ipcNamespace: "some-app", +}); +``` + +**Renderer process** + +```javascript +import * as Sentry from "@sentry/electron/renderer"; + +Sentry.init({ + ipcNamespace: "some-app", +}); +``` + +**Preload process** + +```javascript +import { hookupIpc } from "@sentry/electron/preload-namespaced"; + +hookupIpc("some-app"); +``` + +The SDK will prefix all IPC channels with your specified namespace (for example, `some-app`), helping to avoid conflicts with other channels in your application. + +For more configuration options, see the configuration options documentation. + +## Preload Injection + +The SDK automatically injects a preload script using [`session.setPreloads(preloads)`](https://www.electronjs.org/docs/latest/api/session#sessetpreloadspreloads). By default, this only applies to the `defaultSession`. + +If your app uses other sessions, pass them via the `getSessions` option in the `main` process: + +```javascript +import { session } from "electron"; +import * as Sentry from "@sentry/electron/main"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + getSessions: () => [ + session.defaultSession, + session.fromPartition("persist:my-session"), + ], +}); +``` + + + If your app bundles the `main` process JavaScript, the SDK can't automatically + inject preload scripts because they won't be included in 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 prefer to bundle and configure the preload script manually, import the SDK preload code into your own preload script: + +```javascript +import "@sentry/electron/preload"; +``` + +This exposes IPC to the isolated renderer via Electron's `contextBridge` API. + +Check out our [example apps](https://github.com/getsentry/sentry-electron/tree/master/examples) for implementation details. diff --git a/docs/platforms/javascript/guides/electron/features/native-crash-reporting.mdx b/docs/platforms/javascript/guides/electron/features/native-crash-reporting.mdx new file mode 100644 index 0000000000000..a4fe1d07d763f --- /dev/null +++ b/docs/platforms/javascript/guides/electron/features/native-crash-reporting.mdx @@ -0,0 +1,72 @@ +--- +title: Native Crash Reporting +description: "Learn how Sentry captures and processes native crashes from Electron processes." +--- + +Sentry can process Minidumps created when any Electron process crashes. The SDK uploads these files when the application restarts (or immediately after a renderer crash). All event metadata, including user information and breadcrumbs, is included in these uploads. + +Due to [macOS App Store sandbox restrictions](https://electronjs.org/docs/tutorial/mac-app-store-submission-guide#limitations-of-mas-build), native crashes can't be collected in Mac App Store builds. Native crash handling is automatically disabled in these environments. + + + Minidumps are memory snapshots of a process at the moment it crashes. They may + contain sensitive information, such as environment variables, local path + names, or even in-memory data from input fields, including passwords. **Sentry + does not store these memory dumps**. Once processed, Sentry immediately + deletes them and strips all sensitive information from the resulting Issues. + + + + It's currently not possible to send events from native code (such as a C++ + extension). However, crashes will still be reported to Sentry if they happen + in a process where the SDK has been configured. Additionally, crash reports + from sub-processes may not be reported automatically on all platforms. This + feature will be added in a future SDK update. + + +## Symbolication + +To allow Sentry to process native crashes and fully provide symbolicated stack traces, you need to upload _Debug Information Files_ (sometimes also referred to as _Debug Symbols_ or just _Symbols_). Without these symbols, crash reports will show memory addresses instead of function names and file locations. + +For standard Electron apps, enable the built-in Electron Symbol Server in Sentry: + +1. Go **Project Settings > Debug Files** +2. Select `Electron` from the **Built-in Repositories** +3. Add symbol servers for the platforms you're deploying to (if needed) + +### Custom Code and Extensions + +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. + +For detailed instructions on uploading and managing debug symbols, see the [Debug Information Files](/platforms/javascript/guides/electron/data-management/debug-files/) documentation. + +## Child Processes + +The SDK relies on the [Electron crashReporter](https://electronjs.org/docs/api/crash-reporter) to capture crash dumps. To receive crash reports for child processes, make sure the crash reporter is activated by either the SDK or manually (see [Manual Crash Reporting below](#manual-crash-reporting)). + +Once active, the SDK automatically captures native crashes for the following processes: + +| | `event.process` tag | macOS | Windows | Linux | +| --------------------------- | ------------------- | ----- | ------- | -------------- | +| Electron `main` process | `browser` | ✓ | ✓ | ✓ | +| Electron `renderer` process | `renderer` | ✓ | ✓ | ✓ | +| Electron `utilityProcess` | `utility` | ✓ | ✓ | ✓ 1 | +| `child_process.fork` | `node` | ✓ | ✓ | | +| `child_process.exec/spawn` | `unknown` | ✓ | | | + +1 Not supported in Electron v29.4.6. + +## Manual Crash Reporting + +You can also capture native crashes by manually starting the [Electron `crashReporter`](https://electronjs.org/docs/api/crash-reporter). This approach provides symbolicated stack traces and system information, but doesn't include Electron-specific metadata, breadcrumbs, or context information. + +This is useful when you can't use the full Electron SDK: + +```javascript +const { crashReporter } = require("electron"); +crashReporter.start({ + companyName: "YourCompany", + productName: "YourApp", + ignoreSystemCrashHandler: true, + submitURL: "___MINIDUMP_URL___", +}); +``` diff --git a/docs/platforms/javascript/guides/electron/features/offline-support.mdx b/docs/platforms/javascript/guides/electron/features/offline-support.mdx new file mode 100644 index 0000000000000..cf241471bbd55 --- /dev/null +++ b/docs/platforms/javascript/guides/electron/features/offline-support.mdx @@ -0,0 +1,52 @@ +--- +title: Offline Support +description: "Learn how to customize the automatic caching of Sentry events while being offline." +--- + +Sentry automatically handles offline event caching across the main and renderer processes to make sure you don't miss important information. + +You can customize the queueing behavior with these optional [`transportOptions`](/platforms/javascript/guides/electron/configuration/options/#transportOptions) properties: + +```javascript +import * as Sentry from "@sentry/electron/main"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + transportOptions: { + /* The maximum number of days to keep an envelope in the queue. */ + maxAgeDays: 30, + /* The maximum number of envelopes to keep in the queue. */ + maxQueueSize: 30, + /** + * Called before we attempt to send an envelope to Sentry. + * + * If this function returns false, `shouldStore` will be called to determine if the envelope should be stored. + * + * Default: () => true + * + * @param envelope The envelope that will be sent. + * @returns Whether we should attempt to send the envelope + */ + shouldSend: (envelope: Envelope) => boolean | Promise; + /** + * Called before an event is stored. + * + * Return false to drop the envelope rather than store it. + * + * Default: () => true + * + * @param envelope The envelope that failed to send. + * @param error The error that occurred. + * @param retryDelay The current retry delay in milliseconds. + * @returns Whether we should store the envelope in the queue + */ + shouldStore: (envelope: Envelope, error: Error, retryDelay: number) => boolean | Promise; + /** + * Should the offline store flush shortly after startup. + * + * Defaults: false + */ + flushAtStartup: false; + }, +}); +``` diff --git a/docs/platforms/javascript/guides/electron/index.mdx b/docs/platforms/javascript/guides/electron/index.mdx index 004c42addea50..f86092d85198a 100644 --- a/docs/platforms/javascript/guides/electron/index.mdx +++ b/docs/platforms/javascript/guides/electron/index.mdx @@ -156,222 +156,11 @@ init( ); ``` -## Step 3: Offline Support - -The default transport automatically handles offline events caching from both the -main and renderer processes. Here are several options that allow you to customize queueing behavior: - -```javascript -import * as Sentry from "@sentry/electron/main"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - transportOptions: { - /* The maximum number of days to keep an envelope in the queue. */ - maxAgeDays: 30, - /* The maximum number of envelopes to keep in the queue. */ - maxQueueSize: 30, - /** - * Called before we attempt to send an envelope to Sentry. - * - * If this function returns false, `shouldStore` will be called to determine if the envelope should be stored. - * - * Default: () => true - * - * @param envelope The envelope that will be sent. - * @returns Whether we should attempt to send the envelope - */ - shouldSend: (envelope: Envelope) => boolean | Promise; - /** - * Called before an event is stored. - * - * Return false to drop the envelope rather than store it. - * - * Default: () => true - * - * @param envelope The envelope that failed to send. - * @param error The error that occurred. - * @param retryDelay The current retry delay in milliseconds. - * @returns Whether we should store the envelope in the queue - */ - shouldStore: (envelope: Envelope, error: Error, retryDelay: number) => boolean | Promise; - /** - * Should the offline store flush shortly after startup. - * - * Defaults: false - */ - flushAtStartup: false; - }, -}); -``` - -## Step 4: Inter-Process Communication (Optional) - -To provide the most detailed context for all events, including native crashes, the SDK merges context, scope, and breadcrumbs from all processes into the Electron `main` process. - -By default, the SDK attempts to establish communication from `renderer` to `main` via Electron IPC APIs, 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`. - -```javascript -const { init, IPCMode } = require("@sentry/electron/main"); - -init({ - dsn: "___PUBLIC_DSN___", - debug: true, - ipcMode: IPCMode.Protocol, -}); -``` - -### Custom IPC Namespace - -If your Electron application uses multiple IPC channels and you want to prevent potential conflicts between them, you can specify a custom namespace for the IPC channels used by Sentry with the `ipcNamespace` option. - -To use a custom namespace, you need to configure it in all three contexts: main process, renderer processes, and preload scripts. - -**In the main process:** - -```javascript -import * as Sentry from "@sentry/electron/main"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - ipcNamespace: "some-app", -}); -``` - -**In renderer processes:** - -```javascript -import * as Sentry from "@sentry/electron/renderer"; - -Sentry.init({ - ipcNamespace: "some-app", -}); -``` - -**In preload scripts:** - -```javascript -import { hookupIpc } from "@sentry/electron/preload-namespaced"; - -hookupIpc("some-app"); -``` - -When set, the IPC channels used by Sentry will be prefixed with the specified namespace (e.g., `some-app`), helping to avoid conflicts with other IPC channels in your application. Make sure to use the same namespace value across all processes for proper communication. - -For more configuration options, see the configuration options documentation. - -### Preload Injection - -The SDK attempts to inject a preload script via [`session.setPreloads(preloads)`](https://www.electronjs.org/docs/latest/api/session#sessetpreloadspreloads) 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: - -```javascript -import { session } from "electron"; -import * as Sentry from "@sentry/electron/main"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - 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: - -```javascript -import "@sentry/electron/preload"; -``` - -This script exposes IPC to the isolated renderer via Electron's `contextBridge` API. - -Check out the [example apps](https://github.com/getsentry/sentry-electron/tree/master/examples) for how to do this. - -## Step 5: Debug Information (Optional) - -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_](/platforms/javascript/guides/electron/#native). - - - -It is currently not possible to send events from native code (such as a C++ extension). However, crashes will still be reported to Sentry if they happen in a process where the SDK has been configured. Additionally, crash reports from sub-processes will not be reported automatically on all platforms. This feature will be added in a future SDK update. - - - -## Step 6: Add Readable Stack Traces With Source Maps (Optional) +## Step 3: Add Readable Stack Traces With Source Maps (Optional) -## Step 7: Native (Optional) - -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 metadata, including user information and breadcrumbs, is included in these uploads. - -Due to [restrictions of macOS app sandboxing](https://electronjs.org/docs/tutorial/mac-app-store-submission-guide#limitations-of-mas-build), native crashes cannot be collected in Mac App Store builds. In this case, native crash handling will be disabled. - - - -Minidumps are memory dumps of the process at the moment it crashes. As such, they might contain sensitive information on the target system, such as environment variables, local path names, or maybe even in-memory representations of input fields including passwords. **Sentry does not store these memory dumps**. Once processed, they are removed immediately, and all sensitive information is stripped from the resulting issues. - - - -### 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_](/platforms/javascript/guides/electron/data-management/debug-files/) for a detailed description of how to -set up Sentry for native development. Additionally, see [_Uploading Debug -Information_](/cli/dif/) for details on the upload process. - -### Child Processes - -The SDK relies on the [Electron crashReporter](https://electronjs.org/docs/api/crash-reporter) to capture crash dumps. To receive crash reports for child processes, ensure the crash reporter is activated by either the SDK or manually (see [below](/platforms/javascript/guides/electron/#manual-crash-reporting)). - -Once the crash reporter is active, the SDK will automatically capture native -crashes for the following processes: - -| | `event.process` tag | macOS | Windows | Linux | -| --------------------------- | ------------------- | ----- | ------- | -------------- | -| Electron `main` process | `browser` | ✓ | ✓ | ✓ | -| Electron `renderer` process | `renderer` | ✓ | ✓ | ✓ | -| Electron `utilityProcess` | `utility` | ✓ | ✓ | ✓ 1 | -| `child_process.fork` | `node` | ✓ | ✓ | | -| `child_process.exec/spawn` | `unknown` | ✓ | | | - -1 Not working with Electron v29.4.6. - -### Manual Crash Reporting - -You can also capture native crashes by starting the [Electron CrashReporter](https://electronjs.org/docs/api/crash-reporter) manually. Sentry can 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: - -```javascript -const { crashReporter } = require("electron"); -crashReporter.start({ - companyName: "YourCompany", - productName: "YourApp", - ignoreSystemCrashHandler: true, - submitURL: "___MINIDUMP_URL___", -}); -``` - -## Step 8: Verify Your Setup +## Step 4: Verify Your Setup Let's test your setup and confirm that Sentry is working correctly. @@ -443,6 +232,7 @@ Now's a good time to customize your setup and look into more advanced topics. Ou - Continue to customize your configuration - Learn how to manually capture errors +- Make use of Electron-specific features - Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts