diff --git a/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx b/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx index ed2a10c30b7a8..07f5a2ee7364b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx @@ -50,6 +50,8 @@ pnpm add @sentry/node-native ## Usage + + If you instrument your application via the Node.js `--import` flag, Sentry will be started and this instrumentation will be automatically applied to all worker threads. `instrument.mjs` @@ -88,6 +90,24 @@ node --import instrument.mjs app.mjs If a thread is blocked for more than the configured threshold, stack traces are automatically captured for all threads and sent to Sentry. + + + + +_(Available in version 6.9.0 and above)_ + +```javascript +import * as Sentry from "@sentry/electron/main"; +import { eventLoopBlockIntegration } from "@sentry/electron/native"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [eventLoopBlockIntegration({ threshold: 500 })], +}); +``` + + + ## Configuration Options You can pass a configuration object to the `eventLoopBlockIntegration` to customize the behavior: @@ -112,6 +132,7 @@ interface ThreadBlockedIntegrationOptions { staticTags: { [key: string]: Primitive }; } ``` + ## Example Configuration @@ -132,3 +153,5 @@ Sentry.init({ ], }); ``` + + diff --git a/docs/platforms/javascript/guides/electron/configuration/event-loop-block.mdx b/docs/platforms/javascript/guides/electron/configuration/event-loop-block.mdx index 6953732abb459..52cb93c270074 100644 --- a/docs/platforms/javascript/guides/electron/configuration/event-loop-block.mdx +++ b/docs/platforms/javascript/guides/electron/configuration/event-loop-block.mdx @@ -12,34 +12,73 @@ keywords: --- Event Loop Block errors, or Application Not Responding (ANR) errors are -triggered when the Electron main or renderer processes event loop is blocked for more than -five seconds. The Electron SDK reports ANR errors as Sentry events and can -optionally attach a stack trace of the blocking code to the ANR event. +triggered when the Electron main or renderer processes event loop is blocked for +more than the configured threshold. The Electron SDK reports ANR errors as +Sentry events and can attach a stack trace of the blocking code to the ANR +event. -_(Available in version 4.17.0 and above)_ +_(Available in version 6.9.0 and above)_ - +Event loop blocked detection can be individually enabled for the main and +renderer processes. -ANR detection requires Electron v22 or higher. +# Main Process: - +## Installation -ANR tracking can be individually enabled for the main and renderer processes. +Install `@sentry/node-native` to use the `eventLoopBlockIntegration` in the main +process. -For the main process: +```bash {tabTitle:npm} +npm install @sentry/node-native +``` + +```bash {tabTitle:yarn} +yarn add @sentry/node-native +``` + +```bash {tabTitle:pnpm} +pnpm add @sentry/node-native +``` + +## Usage ```javascript import * as Sentry from "@sentry/electron/main"; +import { eventLoopBlockIntegration } from "@sentry/electron/native"; Sentry.init({ dsn: "___PUBLIC_DSN___", - integrations: [Sentry.anrIntegration({ captureStackTrace: true })], + integrations: [eventLoopBlockIntegration({ threshold: 500 })], }); ``` -For renderer processes: +## Configuration options + +```typescript +export interface ThreadBlockedIntegrationOptions { + /** + * Threshold in milliseconds to trigger an event. + * + * Defaults to 1000ms. + */ + threshold: number; + /** + * Maximum number of blocked events to send per clock hour. + * + * Defaults to 1. + */ + maxEventsPerHour: number; + /** + * Tags to include with blocked events. + */ + staticTags: { [key: string]: Primitive }; +} +``` + +# Renderer Processes: ```javascript import * as Sentry from "@sentry/electron/renderer"; @@ -52,8 +91,8 @@ Sentry.init({ ## Configuration options -You can pass a configuration object to both the `Anr` integration and the -`anrDetection` renderer option to customize the ANR detection behavior. +You can pass a configuration object for `anrDetection` in the renderer to +customize the ANR detection behavior. ```Typescript interface Options { @@ -79,21 +118,22 @@ interface Options { } ``` -## Application Not Responding (ANR) Implementation and Overhead - -ANR detection in the Electron main process uses a worker thread to monitor the event loop -in the main app thread. The main app thread sends a heartbeat message to the ANR -worker thread every 50ms. If the ANR worker does not receive a heartbeat message -for 5 seconds, it triggers an ANR event. If the `captureStackTrace` option is -enabled, the ANR worker uses the `inspector` module to capture stack traces via the [v8 -inspector API](https://nodejs.org/api/inspector.html). - -Once an ANR event is reported, the ANR worker thread exits to prevent further -duplicate events and the main app thread will continue to run as usual. - -Overhead from Node.js ANR tracking should be minimal. With no ANR detected, the -only overhead in the main app thread is polling the ANR worker over IPC every 50ms by -default. The ANR worker thread consumes around 10-20 MB of RAM to keep track of -the polling. Once an ANR has been detected, the main thread is paused briefly -in the debugger to capture the stack trace frames. At this point, the event loop -has been blocked for seconds so the debugging overhead is negligible. +## Event Loop Block Detection Implementation and Overhead + +In the main process, the `eventLoopBlockIntegration` uses a native module to +track threads and capture stack traces via v8's native APIs. A worker thread is +used to capture events even if the main thread is blocked. Overhead with no +event loop blocking should be minimal. Each thread notifies the native module +that it is alive every `threshold / 2` milliseconds. Once an event loop block is +detected, v8's native APIs are used to pause all threads and capture stack +traces. The pause time is considered inconsequential if the event loop has +already been blocked for hundreds of milliseconds. + +In the renderer processes, a similar polling mechanism is used to detect event +loop blocks. In Electron v34 or newer, the +[`frame.collectJavaScriptCallStack()`](https://www.electronjs.org/docs/latest/api/web-frame-main#framecollectjavascriptcallstack-experimental) +API is used to capture stack traces when an event loop block is detected. In +older Electron versions, the `v8` inspector API is used to capture stack traces. +The inspector API can have a slight negative impact on performance since it can +cause v8 to de-optimize some code paths. For this reason we recommend updating +to Electron v34 or newer to use this feature in production.