0
# Node.js System Integrations
1

2
Node.js-specific integrations for handling uncaught exceptions, unhandled rejections, and system-level monitoring.
3

4
## Capabilities
5

6
### Exception and Rejection Handlers
7

8
Automatic capture of uncaught exceptions and unhandled promise rejections.
9

10
```typescript { .api }
11
/**
12
 * Create integration for capturing uncaught exceptions
13
 * @param options - Uncaught exception handler configuration options
14
 * @returns Uncaught exception integration instance
15
 */
16
function onUncaughtExceptionIntegration(options?: UncaughtExceptionOptions): Integration;
17

18
/**
19
 * Create integration for capturing unhandled promise rejections
20
 * @param options - Unhandled rejection handler configuration options
21
 * @returns Unhandled rejection integration instance
22
 */
23
function onUnhandledRejectionIntegration(options?: UnhandledRejectionOptions): Integration;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import * as Sentry from "@sentry/node";
30

31
// Initialize with exception handlers
32
Sentry.init({
33
  dsn: "YOUR_DSN",
34
  integrations: [
35
    Sentry.onUncaughtExceptionIntegration({
36
      exitEvenIfOtherHandlersAreRegistered: false,
37
    }),
38
    Sentry.onUnhandledRejectionIntegration({
39
      mode: "warn", // "strict", "warn", or "none"
40
    }),
41
  ],
42
});
43

44
// These will be automatically captured
45
throw new Error("This uncaught exception will be sent to Sentry");
46

47
Promise.reject(new Error("This unhandled rejection will be sent to Sentry"));
48

49
// Async function without proper error handling
50
async function riskyOperation() {
51
  throw new Error("This error will be captured as unhandled rejection");
52
}
53
riskyOperation(); // Called without await or .catch()
54
```
55

56
### Node.js Context Integration
57

58
Capture Node.js-specific context information.
59

60
```typescript { .api }
61
/**
62
 * Create Node.js context integration for capturing runtime information
63
 * @returns Node.js context integration instance
64
 */
65
function nodeContextIntegration(): Integration;
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import * as Sentry from "@sentry/node";
72

73
// Initialize with Node.js context
74
Sentry.init({
75
  dsn: "YOUR_DSN",
76
  integrations: [
77
    Sentry.nodeContextIntegration(),
78
  ],
79
});
80

81
// Context automatically includes:
82
// - Node.js version
83
// - Platform information
84
// - Memory usage
85
// - Process uptime
86
// - Environment variables (filtered)
87
```
88

89
### Local Variables Integration
90

91
Capture local variables in stack traces for debugging.
92

93
```typescript { .api }
94
/**
95
 * Create local variables integration for capturing variable values in stack traces
96
 * @param options - Local variables configuration options
97
 * @returns Local variables integration instance
98
 */
99
function localVariablesIntegration(options?: LocalVariablesOptions): Integration;
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
import * as Sentry from "@sentry/node";
106

107
// Initialize with local variables capture
108
Sentry.init({
109
  dsn: "YOUR_DSN",
110
  integrations: [
111
    Sentry.localVariablesIntegration({
112
      captureAllExceptions: true, // Capture for all exceptions
113
      maxExceptionsPerSecond: 5, // Rate limit to avoid performance impact
114
    }),
115
  ],
116
});
117

118
function processUserData(userId, userData) {
119
  const processedData = transformData(userData);
120
  const validationResult = validateData(processedData);
121
  
122
  if (!validationResult.isValid) {
123
    // When this error is captured, local variables will be included:
124
    // userId, userData, processedData, validationResult
125
    throw new Error("Data validation failed");
126
  }
127
  
128
  return processedData;
129
}
130
```
131

132
### Context Lines Integration
133

134
Add source code context around stack trace lines.
135

136
```typescript { .api }
137
/**
138
 * Create context lines integration for adding source code context to stack traces
139
 * @param options - Context lines configuration options
140
 * @returns Context lines integration instance
141
 */
142
function contextLinesIntegration(options?: ContextLinesOptions): Integration;
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import * as Sentry from "@sentry/node";
149

150
// Initialize with context lines
151
Sentry.init({
152
  dsn: "YOUR_DSN",
153
  integrations: [
154
    Sentry.contextLinesIntegration({
155
      frameContextLines: 5, // Number of lines before/after each stack frame
156
    }),
157
  ],
158
});
159

160
// Stack traces will include source code context around each frame
161
function calculateTotal(items) {
162
  let total = 0;
163
  for (const item of items) {
164
    total += item.price; // If error occurs here, surrounding code will be shown
165
  }
166
  return total;
167
}
168
```
169

170
### Modules Integration
171

172
Capture information about loaded Node.js modules.
173

174
```typescript { .api }
175
/**
176
 * Create modules integration for capturing loaded module information
177
 * @returns Modules integration instance
178
 */
179
function modulesIntegration(): Integration;
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
import * as Sentry from "@sentry/node";
186

187
// Initialize with modules integration
188
Sentry.init({
189
  dsn: "YOUR_DSN",
190
  integrations: [
191
    Sentry.modulesIntegration(),
192
  ],
193
});
194

195
// Events will include information about:
196
// - All loaded npm packages and their versions
197
// - Built-in Node.js modules in use
198
// - Module loading order and dependencies
199
```
200

201
### Child Process Integration
202

203
Instrument child process operations.
204

205
```typescript { .api }
206
/**
207
 * Create child process integration for tracing subprocess operations
208
 * @param options - Child process configuration options
209
 * @returns Child process integration instance
210
 */
211
function childProcessIntegration(options?: ChildProcessOptions): Integration;
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
import * as Sentry from "@sentry/node";
218
import { spawn, exec } from "child_process";
219

220
// Initialize with child process integration
221
Sentry.init({
222
  dsn: "YOUR_DSN",
223
  integrations: [
224
    Sentry.childProcessIntegration({
225
      captureSpawns: true, // Trace child process spawns
226
      captureExecs: true,  // Trace exec operations
227
    }),
228
  ],
229
});
230

231
// These operations will create spans
232
const child = spawn("ls", ["-la"]);
233
child.on("close", (code) => {
234
  console.log(`Child process exited with code ${code}`);
235
});
236

237
exec("node --version", (error, stdout, stderr) => {
238
  if (error) {
239
    console.error(`exec error: ${error}`);
240
    return;
241
  }
242
  console.log(`stdout: ${stdout}`);
243
});
244
```
245

246
### File System Integration
247

248
Instrument file system operations.
249

250
```typescript { .api }
251
/**
252
 * Create file system integration for tracing fs operations
253
 * @param options - File system configuration options
254
 * @returns File system integration instance
255
 */
256
function fsIntegration(options?: FsOptions): Integration;
257
```
258

259
**Usage Examples:**
260

261
```typescript
262
import * as Sentry from "@sentry/node";
263
import fs from "fs/promises";
264
import path from "path";
265

266
// Initialize with fs integration
267
Sentry.init({
268
  dsn: "YOUR_DSN",
269
  integrations: [
270
    Sentry.fsIntegration({
271
      captureAsyncOperations: true, // Trace async fs operations
272
      captureSyncOperations: false, // Don't trace sync operations (performance)
273
    }),
274
  ],
275
});
276

277
// These operations will create spans
278
const content = await fs.readFile("data.json", "utf8");
279
await fs.writeFile("output.json", JSON.stringify(data));
280
const stats = await fs.stat("myfile.txt");
281
```
282

283
### System Error Integration
284

285
Capture system-level errors and signals.
286

287
```typescript { .api }
288
/**
289
 * Create system error integration for capturing system-level errors
290
 * @returns System error integration instance
291
 */
292
function systemErrorIntegration(): Integration;
293
```
294

295
**Usage Examples:**
296

297
```typescript
298
import * as Sentry from "@sentry/node";
299

300
// Initialize with system error integration
301
Sentry.init({
302
  dsn: "YOUR_DSN",
303
  integrations: [
304
    Sentry.systemErrorIntegration(),
305
  ],
306
});
307

308
// Captures system events like:
309
// - SIGTERM, SIGINT signals
310
// - Memory limit exceeded
311
// - File descriptor limits
312
// - Network errors
313
```
314

315
### Context and Module Integrations
316

317
Integrations for enhanced context capture and module information.
318

319
```typescript { .api }
320
/**
321
 * Create context lines integration for capturing source code around stack frames
322
 * @param options - Context lines configuration options
323
 * @returns Context lines integration instance
324
 */
325
function contextLinesIntegration(options?: ContextLinesOptions): Integration;
326

327
/**
328
 * Create modules integration for capturing loaded module information
329
 * @returns Modules integration instance
330
 */
331
function modulesIntegration(): Integration;
332

333
/**
334
 * Create node context integration for capturing Node.js environment context
335
 * @returns Node context integration instance
336
 */
337
function nodeContextIntegration(): Integration;
338
```
339

340
**Usage Examples:**
341

342
```typescript
343
import * as Sentry from "@sentry/node";
344

345
// Initialize with context and module integrations
346
Sentry.init({
347
  dsn: "YOUR_DSN",
348
  integrations: [
349
    Sentry.contextLinesIntegration({
350
      frameContextLines: 5, // Lines of code to show around each stack frame
351
    }),
352
    Sentry.modulesIntegration(), // Include loaded modules in error reports
353
    Sentry.nodeContextIntegration(), // Include Node.js runtime context
354
  ],
355
});
356

357
// Enhanced error reports will include:
358
// - Source code lines around each stack frame
359
// - List of loaded modules and versions
360
// - Node.js runtime information (version, platform, etc.)
361
```
362

363
### Third-Party Service Integrations
364

365
Integrations for popular third-party services and libraries.
366

367
```typescript { .api }
368
/**
369
 * Create Supabase integration for database and API tracing
370
 * @param options - Supabase integration configuration options
371
 * @returns Supabase integration instance
372
 */
373
function supabaseIntegration(options?: SupabaseOptions): Integration;
374

375
/**
376
 * Instrument Supabase client for automatic tracing
377
 * @param client - Supabase client instance
378
 * @returns Instrumented client
379
 */
380
function instrumentSupabaseClient<T>(client: T): T;
381

382
/**
383
 * Create Zod errors integration for enhanced validation error reporting
384
 * @param options - Zod errors configuration options
385
 * @returns Zod errors integration instance
386
 */
387
function zodErrorsIntegration(options?: ZodErrorsOptions): Integration;
388

389
/**
390
 * Create Winston transport for sending logs to Sentry
391
 * @param options - Winston transport configuration options
392
 * @returns Sentry Winston transport instance
393
 */
394
function createSentryWinstonTransport(options?: WinstonTransportOptions): Transport;
395
```
396

397
**Usage Examples:**
398

399
```typescript
400
import * as Sentry from "@sentry/node";
401
import { createClient } from "@supabase/supabase-js";
402
import { z } from "zod";
403
import winston from "winston";
404

405
// Initialize with third-party integrations
406
Sentry.init({
407
  dsn: "YOUR_DSN",
408
  integrations: [
409
    Sentry.supabaseIntegration({
410
      captureQueries: true,
411
      captureAuth: true, // Track authentication events
412
    }),
413
    Sentry.zodErrorsIntegration({
414
      captureValidationErrors: true,
415
      enhanceErrorMessages: true,
416
    }),
417
  ],
418
});
419

420
// Supabase client - automatically traced
421
const supabase = Sentry.instrumentSupabaseClient(
422
  createClient("https://your-project.supabase.co", "your-anon-key")
423
);
424

425
// Database operations will create spans
426
const { data, error } = await supabase
427
  .from("users")
428
  .select("*")
429
  .eq("active", true);
430

431
// Zod validation errors will be enhanced
432
const userSchema = z.object({
433
  name: z.string().min(2),
434
  email: z.string().email(),
435
  age: z.number().min(18),
436
});
437

438
try {
439
  userSchema.parse({ name: "A", email: "invalid", age: 15 });
440
} catch (error) {
441
  // Enhanced Zod error information will be sent to Sentry
442
  Sentry.captureException(error);
443
}
444

445
// Winston logger with Sentry transport
446
const logger = winston.createLogger({
447
  transports: [
448
    new winston.transports.Console(),
449
    Sentry.createSentryWinstonTransport({
450
      level: "error", // Only send error level logs to Sentry
451
      silent: false,
452
    }),
453
  ],
454
});
455

456
logger.error("This error will be sent to both console and Sentry");
457
```
458

459
### Development Tools
460

461
Integration for development and debugging tools.
462

463
```typescript { .api }
464
/**
465
 * Create Spotlight integration for development debugging
466
 * @param options - Spotlight configuration options
467
 * @returns Spotlight integration instance
468
 */
469
function spotlightIntegration(options?: SpotlightOptions): Integration;
470
```
471

472
**Usage Examples:**
473

474
```typescript
475
import * as Sentry from "@sentry/node";
476

477
// Initialize with Spotlight for development
478
Sentry.init({
479
  dsn: "YOUR_DSN",
480
  integrations: [
481
    Sentry.spotlightIntegration({
482
      sidecarUrl: "http://localhost:8969", // Spotlight sidecar URL
483
    }),
484
  ],
485
});
486

487
// When running with Spotlight:
488
// - View real-time errors and traces in browser
489
// - Debug performance issues locally
490
// - Inspect event data before it goes to Sentry
491
```
492

493
## Types
494

495
### Integration Options
496

497
```typescript { .api }
498
interface UncaughtExceptionOptions {
499
  /** Exit process even if other handlers are registered */
500
  exitEvenIfOtherHandlersAreRegistered?: boolean;
501
}
502

503
interface UnhandledRejectionOptions {
504
  /** Mode for handling unhandled rejections */
505
  mode?: "strict" | "warn" | "none";
506
}
507

508
interface LocalVariablesOptions {
509
  /** Capture local variables for all exceptions */
510
  captureAllExceptions?: boolean;
511
  /** Maximum number of exceptions to capture per second */
512
  maxExceptionsPerSecond?: number;
513
  /** Maximum depth for variable capture */
514
  maxDepth?: number;
515
  /** Maximum number of properties per object */
516
  maxProperties?: number;
517
}
518

519
interface ContextLinesOptions {
520
  /** Number of lines to include before/after each stack frame */
521
  frameContextLines?: number;
522
}
523

524
interface ChildProcessOptions {
525
  /** Capture child process spawn operations */
526
  captureSpawns?: boolean;
527
  /** Capture exec operations */
528
  captureExecs?: boolean;
529
  /** Maximum command length to capture */
530
  maxCommandLength?: number;
531
}
532

533
interface FsOptions {
534
  /** Capture asynchronous file system operations */
535
  captureAsyncOperations?: boolean;
536
  /** Capture synchronous file system operations */
537
  captureSyncOperations?: boolean;
538
  /** File path patterns to ignore */
539
  ignorePatterns?: string[];
540
}
541

542
interface SpotlightOptions {
543
  /** Spotlight sidecar URL */
544
  sidecarUrl?: string;
545
  /** Enable Spotlight integration */
546
  enabled?: boolean;
547
}
548

549
interface SupabaseOptions {
550
  /** Capture database queries in spans */
551
  captureQueries?: boolean;
552
  /** Track authentication events */
553
  captureAuth?: boolean;
554
  /** Maximum query length to capture */
555
  maxQueryLength?: number;
556
}
557

558
interface ZodErrorsOptions {
559
  /** Capture validation errors from Zod schemas */
560
  captureValidationErrors?: boolean;
561
  /** Enhance error messages with schema information */
562
  enhanceErrorMessages?: boolean;
563
  /** Maximum number of validation errors to include */
564
  maxErrors?: number;
565
}
566

567
interface WinstonTransportOptions {
568
  /** Minimum log level to send to Sentry */
569
  level?: string;
570
  /** Silent mode - don't output to console */
571
  silent?: boolean;
572
  /** Custom formatting function */
573
  format?: any;
574
}
575

576
interface Transport {
577
  log(info: any, next: () => void): void;
578
}
579
```