Skip to content

Commit 6cd4e7d

Browse files
authored
fix: Make sure event loop block integration is documented (#14304)
A bad rebase meant that this was not included with #14302
1 parent 8974643 commit 6cd4e7d

File tree

1 file changed

+134
-0
lines changed

1 file changed

+134
-0
lines changed
Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
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. Stack traces are automatically captured when blocking is detected.
36+
37+
## Installation
38+
39+
```bash {tabTitle:npm}
40+
npm install @sentry/node-native
41+
```
42+
43+
```bash {tabTitle:yarn}
44+
yarn add @sentry/node-native
45+
```
46+
47+
```bash {tabTitle:pnpm}
48+
pnpm add @sentry/node-native
49+
```
50+
51+
## Usage
52+
53+
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.
54+
55+
`instrument.mjs`
56+
57+
```javascript
58+
import { eventLoopBlockIntegration } from "@sentry/node-native";
59+
60+
Sentry.init({
61+
dsn: "__YOUR_DSN__",
62+
// Monitor event loop blocking for more than 500ms (stack traces automatically captured)
63+
integrations: [eventLoopBlockIntegration({ threshold: 500 })],
64+
});
65+
```
66+
67+
`app.mjs`
68+
69+
```javascript
70+
import { Worker } from "worker_threads";
71+
72+
const worker = new Worker(new URL("./worker.mjs", import.meta.url));
73+
74+
// This main thread will be monitored for blocked event loops
75+
```
76+
77+
`worker.mjs`
78+
79+
```javascript
80+
// This worker thread will also be monitored for blocked event loops too
81+
```
82+
83+
Start your application:
84+
85+
```bash
86+
node --import instrument.mjs app.mjs
87+
```
88+
89+
If a thread is blocked for more than the configured threshold, stack traces are automatically captured for all threads and sent to Sentry.
90+
91+
## Configuration Options
92+
93+
You can pass a configuration object to the `eventLoopBlockIntegration` to customize the behavior:
94+
95+
```typescript
96+
interface ThreadBlockedIntegrationOptions {
97+
/**
98+
* Threshold in milliseconds to trigger an event.
99+
*
100+
* Defaults to 1000ms.
101+
*/
102+
threshold: number;
103+
/**
104+
* Maximum number of blocked events to send per clock hour.
105+
*
106+
* Defaults to 1.
107+
*/
108+
maxEventsPerHour: number;
109+
/**
110+
* Tags to include with blocked events.
111+
*/
112+
staticTags: { [key: string]: Primitive };
113+
}
114+
```
115+
116+
## Example Configuration
117+
118+
```javascript
119+
import { eventLoopBlockIntegration } from "@sentry/node-native";
120+
121+
Sentry.init({
122+
dsn: "__YOUR_DSN__",
123+
integrations: [
124+
eventLoopBlockIntegration({
125+
threshold: 500, // Trigger after 500ms of blocking (stack traces automatically captured)
126+
maxEventsPerHour: 5, // Maximum 5 events per hour
127+
staticTags: {
128+
component: "main-thread",
129+
environment: "production",
130+
},
131+
}),
132+
],
133+
});
134+
```

0 commit comments

Comments
 (0)