Skip to content

feat: Document eventLoopBlockIntegration integration #14302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 9, 2025
Merged

feat: Document eventLoopBlockIntegration integration #14302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
853d244
feat: Document `eventLoopBlockIntegration` integration
AbhiPrasad Jul 9, 2025
ba73f6b
rename to event loop block
AbhiPrasad Jul 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 34 additions & 9 deletions ...figuration/application-not-responding.mdx → ...common/configuration/event-loop-block.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Application Not Responding (ANR)
title: Event Loop Block Detection
sidebar_order: 70
description: "Learn how to turn off or specify ANRs for Node.js"
description: "Monitor for blocked event loops in Node.js applications"
supported:
- javascript.node
- javascript.aws-lambda
Expand All @@ -25,26 +25,51 @@ supported:
- javascript.tanstackstart-react
keywords:
[
"event loop block",
"anr",
"Application Not Responding",
"Event Loop Blocked",
"Event Loop Stalls",
]
---

Application Not Responding (ANR) errors, or Event Loop Stall errors, are triggered when the Node.js main thread event loop of an application is blocked for more than five seconds. The Node SDK reports ANR errors as Sentry events and can optionally attach a stack trace of the blocking code to the ANR event.
Event Loop Block detection monitors when the Node.js main thread event loop is blocked for more than a specified threshold. The Node SDK reports these events to Sentry with automatically captured stack traces to help identify blocking code.

<Include name="feature-stage-beta.mdx" />

<Alert>

ANR detection is not supported for [Node.js clusters](https://nodejs.org/api/cluster.html).
Event loop block detection is not supported for [Node.js clusters](https://nodejs.org/api/cluster.html).

</Alert>

## Event Loop Block Integration (Recommended)

For the best performance and comprehensive monitoring, we recommend using the [`eventLoopBlockIntegration`](./integrations/event-loop-block) from the `@sentry/node-native` package. Stack traces are automatically captured when blocking is detected. This integration can monitor all threads in your Node.js application and provides better performance compared to the deprecated ANR integration.

```javascript
import * as Sentry from "@sentry/node";
import { eventLoopBlockIntegration } from "@sentry/node-native";

Sentry.init({
dsn: "___PUBLIC_DSN___",
integrations: [eventLoopBlockIntegration({ threshold: 1000 })],
});
```

For detailed usage instructions and configuration options, see the [`eventLoopBlockIntegration`](./integrations/event-loop-block) documentation.

## Deprecated Application Not Responding (ANR) Integration

<Alert type="warning">

**Deprecated**: The `anrIntegration` is deprecated. Please use the [`eventLoopBlockIntegration`](./integrations/event-loop-block) instead for better performance and more comprehensive monitoring.

</Alert>

_(Available in version 7.91.0 and above)_

To enable ANR detection, add the `Anr` integration from the `@sentry/node` package.
The legacy ANR integration is still available but deprecated. If you're currently using it, we recommend migrating to the new `eventLoopBlockIntegration`.

<Alert>

Expand All @@ -61,9 +86,9 @@ Sentry.init({

![Example of an ANR error event](./img/anr-node-example.png)

## Configuration options
### Legacy ANR Configuration Options

You can pass a configuration object to the `Anr` integration to customize the ANR detection behavior.
The deprecated ANR integration supports the following configuration options:

```ts
interface Options {
Expand All @@ -90,9 +115,9 @@ interface Options {
}
```

## ANR Implementation and Overhead
### Legacy ANR Implementation and Overhead

ANR detection with the Node SDK uses a worker thread to monitor the event loop
ANR detection with the legacy Node SDK 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
Expand Down
8 changes: 7 additions & 1 deletion docs/platforms/javascript/common/configuration/integrations/anr.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,12 @@ supported:
- javascript.tanstackstart-react
---

<Alert type="warning">

**Deprecated**: This integration is deprecated. Please use the [`eventLoopBlockIntegration`](./event-loop-block) instead for better performance and more comprehensive monitoring.

</Alert>

<Alert>

This integration only works in the Node.js runtime.
Expand All @@ -32,7 +38,7 @@ This integration only works in the Node.js runtime.

_Import name: `Sentry.anrIntegration`_

The `anrIntegration` captures Application Not Responding (ANR)/Event Loop Stall errors and reports them as Sentry events. For more details, see the documentation on [ANR](../../application-not-responding).
The `anrIntegration` captures Application Not Responding (ANR)/Event Loop Stall errors and reports them as Sentry events. For more details, see the documentation on [Event Loop Block Detection](../../event-loop-block).

```JavaScript
Sentry.init({
Expand Down
8 changes: 4 additions & 4 deletions ...figuration/application-not-responding.mdx → ...ectron/configuration/event-loop-block.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Application Not Responding (ANR)
title: Event Loop Block Detection
sidebar_order: 70
description: "Learn how to turn off or specify ANRs for Electron Main Thread"
description: "Monitor for blocked event loops in Electron applications"
keywords:
[
"anr",
Expand All @@ -11,7 +11,7 @@ keywords:
]
---

Application Not Responding (ANR) errors, or Event Loop Stall errors, are
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.
Expand Down Expand Up @@ -79,7 +79,7 @@ interface Options {
}
```

## ANR Implementation and Overhead
## 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
Expand Down
1 change: 1 addition & 0 deletions platform-includes/configuration/integrations/javascript.astro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ Depending on whether an integration enhances the functionality of a particular r
| [`prismaIntegration`](./prisma) | ✓ | | ✓ | |
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
| [`fsIntegration`](./fs) | | | ✓ | |
| [`knexIntegration`](./knex) | | | ✓ | |
Expand Down
1 change: 1 addition & 0 deletions platform-includes/configuration/integrations/javascript.aws-lambda.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
| [`amqplibIntegration`](./amqplib) | | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
| [`fsIntegration`](./fs) | | | ✓ | |
Expand Down
1 change: 1 addition & 0 deletions platform-includes/configuration/integrations/javascript.connect.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
| [`fsIntegration`](./fs) | | | ✓ | |
Expand Down
1 change: 1 addition & 0 deletions platform-includes/configuration/integrations/javascript.fastify.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
| [`fsIntegration`](./fs) | | | ✓ | |
Expand Down
1 change: 1 addition & 0 deletions platform-includes/configuration/integrations/javascript.gcp-functions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
| [`amqplibIntegration`](./amqplib) | | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
| [`fsIntegration`](./fs) | | | ✓ | |
Expand Down
1 change: 1 addition & 0 deletions platform-includes/configuration/integrations/javascript.hapi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
| [`fsIntegration`](./fs) | | | ✓ | |
Expand Down
1 change: 1 addition & 0 deletions platform-includes/configuration/integrations/javascript.nestjs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
| [`fsIntegration`](./fs) | | | ✓ | |
Expand Down
1 change: 1 addition & 0 deletions platform-includes/configuration/integrations/javascript.nextjs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ Depending on whether an integration enhances the functionality of a particular r
| [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ |
| [`prismaIntegration`](./prisma) | ✓ | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
| [`fsIntegration`](./fs) | | | ✓ | |
| [`knexIntegration`](./knex) | | | ✓ | |
Expand Down
1 change: 1 addition & 0 deletions platform-includes/configuration/integrations/javascript.node.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
| [`amqplibIntegration`](./amqplib) | ✓ | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ |
| [`consoleIntegration`](./console) | ✓ | | | ✓ |
| [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | |
Expand Down
3 changes: 2 additions & 1 deletion platform-includes/configuration/integrations/javascript.nuxt.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Depending on whether an integration enhances the functionality of a particular r
### Browser Integrations

| | **Auto Enabled** | **Errors** | **Tracing** | **Replay** | **Additional Context** |
|-------------------------------------------------------|:----------------:|:----------:|:-----------:|:----------:|:----------------------:|
| ----------------------------------------------------- | :--------------: | :--------: | :---------: | :--------: | :--------------------: |
| [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ |
| [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | |
| [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ |
Expand Down Expand Up @@ -73,6 +73,7 @@ Depending on whether an integration enhances the functionality of a particular r
| [`prismaIntegration`](./prisma) | ✓ | | ✓ | |
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
| [`fsIntegration`](./fs) | | | ✓ | |
| [`knexIntegration`](./knex) | | | ✓ | |
Expand Down
3 changes: 2 additions & 1 deletion platform-includes/configuration/integrations/javascript.remix.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Depending on whether an integration enhances the functionality of a particular r
### Browser Integrations

| | **Auto Enabled** | **Errors** | **Tracing** | **Replay** | **Additional Context** |
|-------------------------------------------------------|:----------------:|:----------:|:-----------:|:----------:|:----------------------:|
| ----------------------------------------------------- | :--------------: | :--------: | :---------: | :--------: | :--------------------: |
| [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ |
| [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | |
| [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ |
Expand Down Expand Up @@ -73,6 +73,7 @@ Depending on whether an integration enhances the functionality of a particular r
| [`prismaIntegration`](./prisma) | ✓ | | ✓ | |
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
| [`anrIntegration`](./anr) | | ✓ | | |
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
| [`fsIntegration`](./fs) | | | ✓ | |
| [`knexIntegration`](./knex) | | | ✓ | |
Expand Down
Loading
Loading