Skip to content

Commit 853d244

Browse files
AbhiPrasadAbhiPrasad
committed
feat: Document eventLoopBlockIntegration integration
1 parent 762d0e1 commit 853d244

16 files changed

+184
-9
lines changed

‎docs/platforms/javascript/common/configuration/application-not-responding.mdx‎

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ keywords:
3232
]
3333
---
3434

35-
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.
35+
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 a specified threshold. The Node SDK reports ANR errors as Sentry events and can optionally attach a stack trace of the blocking code to the ANR event.
3636

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

@@ -42,9 +42,33 @@ ANR detection is not supported for [Node.js clusters](https://nodejs.org/api/clu
4242

4343
</Alert>
4444

45+
## Event Loop Block Integration (Recommended)
46+
47+
For the best performance and comprehensive monitoring, we recommend using the [`eventLoopBlockIntegration`](./integrations/event-loop-block) from the `@sentry/node-native` package. This integration can monitor all threads in your Node.js application and provides better performance compared to the deprecated ANR integration.
48+
49+
```javascript
50+
import * as Sentry from "@sentry/node";
51+
import { eventLoopBlockIntegration } from "@sentry/node-native";
52+
53+
Sentry.init({
54+
dsn: "___PUBLIC_DSN___",
55+
integrations: [eventLoopBlockIntegration({ threshold: 1000 })],
56+
});
57+
```
58+
59+
For detailed usage instructions and configuration options, see the [`eventLoopBlockIntegration`](./integrations/event-loop-block) documentation.
60+
61+
## Deprecated ANR Integration
62+
63+
<Alert type="warning">
64+
65+
**Deprecated**: The `anrIntegration` is deprecated. Please use the [`eventLoopBlockIntegration`](./integrations/event-loop-block) instead for better performance and more comprehensive monitoring.
66+
67+
</Alert>
68+
4569
_(Available in version 7.91.0 and above)_
4670

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

4973
<Alert>
5074

@@ -61,9 +85,9 @@ Sentry.init({
6185

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

64-
## Configuration options
88+
### Legacy ANR Configuration Options
6589

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

6892
```ts
6993
interface Options {
@@ -90,9 +114,9 @@ interface Options {
90114
}
91115
```
92116

93-
## ANR Implementation and Overhead
117+
### Legacy ANR Implementation and Overhead
94118

95-
ANR detection with the Node SDK uses a worker thread to monitor the event loop
119+
ANR detection with the legacy Node SDK uses a worker thread to monitor the event loop
96120
in the main app thread. The main app thread sends a heartbeat message to the ANR
97121
worker thread every 50ms. If the ANR worker does not receive a heartbeat message
98122
for 5 seconds, it triggers an ANR event. If the `captureStackTrace` option is

‎docs/platforms/javascript/common/configuration/integrations/anr.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,12 @@ supported:
2424
- javascript.tanstackstart-react
2525
---
2626

27+
<Alert type="warning">
28+
29+
**Deprecated**: This integration is deprecated. Please use the [`eventLoopBlockIntegration`](./event-loop-block) instead for better performance and more comprehensive monitoring.
30+
31+
</Alert>
32+
2733
<Alert>
2834

2935
This integration only works in the Node.js runtime.

‎docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
title: Event Loop Block
3+
description: "Monitor for blocked event loops in all threads of a Node.js application."
4+
supported:
5+
- javascript.node
6+
- javascript.aws-lambda
7+
- javascript.azure-functions
8+
- javascript.connect
9+
- javascript.express
10+
- javascript.fastify
11+
- javascript.gcp-functions
12+
- javascript.hapi
13+
- javascript.hono
14+
- javascript.koa
15+
- javascript.nestjs
16+
- javascript.electron
17+
- javascript.nextjs
18+
- javascript.nuxt
19+
- javascript.solidstart
20+
- javascript.sveltekit
21+
- javascript.remix
22+
- javascript.react-router
23+
- javascript.astro
24+
- javascript.tanstackstart-react
25+
---
26+
27+
<Alert>
28+
29+
This integration only works in the Node.js runtime.
30+
31+
</Alert>
32+
33+
_Import name: `eventLoopBlockIntegration` from `@sentry/node-native`_
34+
35+
The `eventLoopBlockIntegration` can be used to monitor for blocked event loops in all threads of a Node.js application. This integration provides better performance and more comprehensive monitoring compared to the deprecated [`anrIntegration`](./anr).
36+
37+
## Installation
38+
39+
```bash
40+
# Using yarn
41+
yarn add @sentry/node @sentry/node-native
42+
43+
# Using npm
44+
npm install --save @sentry/node @sentry/node-native
45+
```
46+
47+
## Usage
48+
49+
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.
50+
51+
`instrument.mjs`
52+
53+
```javascript
54+
import * as Sentry from "@sentry/node";
55+
import { eventLoopBlockIntegration } from "@sentry/node-native";
56+
57+
Sentry.init({
58+
dsn: "__YOUR_DSN__",
59+
// Capture stack traces when the event loop is blocked for more than 500ms
60+
integrations: [eventLoopBlockIntegration({ threshold: 500 })],
61+
});
62+
```
63+
64+
`app.mjs`
65+
66+
```javascript
67+
import { Worker } from "worker_threads";
68+
69+
const worker = new Worker(new URL("./worker.mjs", import.meta.url));
70+
71+
// This main thread will be monitored for blocked event loops
72+
```
73+
74+
`worker.mjs`
75+
76+
```javascript
77+
// This worker thread will also be monitored for blocked event loops too
78+
```
79+
80+
Start your application:
81+
82+
```bash
83+
node --import instrument.mjs app.mjs
84+
```
85+
86+
If a thread is blocked for more than the configured threshold, stack traces will be captured for all threads and sent to Sentry.
87+
88+
## Configuration Options
89+
90+
You can pass a configuration object to the `eventLoopBlockIntegration` to customize the behavior:
91+
92+
```typescript
93+
interface ThreadBlockedIntegrationOptions {
94+
/**
95+
* Threshold in milliseconds to trigger an event.
96+
*
97+
* Defaults to 1000ms.
98+
*/
99+
threshold: number;
100+
/**
101+
* Maximum number of blocked events to send per clock hour.
102+
*
103+
* Defaults to 1.
104+
*/
105+
maxEventsPerHour: number;
106+
/**
107+
* Tags to include with blocked events.
108+
*/
109+
staticTags: { [key: string]: Primitive };
110+
}
111+
```
112+
113+
## Example Configuration
114+
115+
```javascript
116+
import * as Sentry from "@sentry/node";
117+
import { eventLoopBlockIntegration } from "@sentry/node-native";
118+
119+
Sentry.init({
120+
dsn: "__YOUR_DSN__",
121+
integrations: [
122+
eventLoopBlockIntegration({
123+
threshold: 500, // Trigger after 500ms of blocking
124+
maxEventsPerHour: 5, // Maximum 5 events per hour
125+
staticTags: {
126+
component: "main-thread",
127+
environment: "production",
128+
},
129+
}),
130+
],
131+
});
132+
```

‎platform-includes/configuration/integrations/javascript.astro.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ Depending on whether an integration enhances the functionality of a particular r
7474
| [`prismaIntegration`](./prisma) | ✓ | | ✓ | |
7575
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
7676
| [`anrIntegration`](./anr) | | ✓ | | |
77+
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
7778
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
7879
| [`fsIntegration`](./fs) | | | ✓ | |
7980
| [`knexIntegration`](./knex) | | | ✓ | |

‎platform-includes/configuration/integrations/javascript.aws-lambda.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
| [`amqplibIntegration`](./amqplib) | | | ✓ | |
2222
| [`anrIntegration`](./anr) | | ✓ | | |
2323
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
24+
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
2425
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
2526
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
2627
| [`fsIntegration`](./fs) | | | ✓ | |

‎platform-includes/configuration/integrations/javascript.connect.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
3434
| [`anrIntegration`](./anr) | | ✓ | | |
3535
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
36+
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
3637
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
3738
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
3839
| [`fsIntegration`](./fs) | | | ✓ | |

‎platform-includes/configuration/integrations/javascript.fastify.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
3434
| [`anrIntegration`](./anr) | | ✓ | | |
3535
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
36+
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
3637
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
3738
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
3839
| [`fsIntegration`](./fs) | | | ✓ | |

‎platform-includes/configuration/integrations/javascript.gcp-functions.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
| [`amqplibIntegration`](./amqplib) | | | ✓ | |
2222
| [`anrIntegration`](./anr) | | ✓ | | |
2323
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
24+
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
2425
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
2526
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
2627
| [`fsIntegration`](./fs) | | | ✓ | |

‎platform-includes/configuration/integrations/javascript.hapi.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
3434
| [`anrIntegration`](./anr) | | ✓ | | |
3535
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
36+
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
3637
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
3738
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
3839
| [`fsIntegration`](./fs) | | | ✓ | |

‎platform-includes/configuration/integrations/javascript.nestjs.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | |
3434
| [`anrIntegration`](./anr) | | ✓ | | |
3535
| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ |
36+
| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | |
3637
| [`dataloaderIntegration`](./dataloader) | | | ✓ | |
3738
| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ |
3839
| [`fsIntegration`](./fs) | | | ✓ | |

0 commit comments

Comments
 (0)