0
# Framework Integrations
1

2
Auto-instrumentation for popular Node.js web frameworks including Express, Fastify, Koa, and Hapi.
3

4
## Capabilities
5

6
### Express.js Integration
7

8
Automatic instrumentation and error handling for Express.js applications.
9

10
```typescript { .api }
11
/**
12
 * Create Express.js integration for automatic instrumentation
13
 * @param options - Express integration configuration options
14
 * @returns Express integration instance
15
 */
16
function expressIntegration(options?: ExpressOptions): Integration;
17

18
/**
19
 * Create Express error handler middleware
20
 * @param options - Error handler configuration options
21
 * @returns Express error handler middleware
22
 */
23
function expressErrorHandler(options?: ExpressErrorHandlerOptions): RequestHandler;
24

25
/**
26
 * Setup Express error handler on an Express app
27
 * @param app - Express application instance
28
 * @param options - Error handler configuration options
29
 */
30
function setupExpressErrorHandler(app: Express, options?: ExpressErrorHandlerOptions): void;
31
```
32

33
**Usage Examples:**
34

35
```typescript
36
import * as Sentry from "@sentry/node";
37
import express from "express";
38

39
// Initialize with Express integration
40
Sentry.init({
41
  dsn: "YOUR_DSN",
42
  integrations: [
43
    Sentry.expressIntegration({
44
      router: true, // Capture router layer info
45
      user: ["id", "username", "email"], // User keys to capture
46
    }),
47
  ],
48
});
49

50
const app = express();
51

52
// Setup error handler
53
Sentry.setupExpressErrorHandler(app, {
54
  shouldHandleError: (error) => {
55
    // Only handle 5xx errors
56
    return error.status >= 500;
57
  },
58
});
59

60
// Or use error handler middleware directly
61
app.use(Sentry.expressErrorHandler({
62
  shouldHandleError: (error) => error.status >= 500,
63
}));
64

65
// Manual Express setup with middleware
66
app.use((req, res, next) => {
67
  // Request will be automatically traced
68
  next();
69
});
70

71
app.get("/users/:id", (req, res) => {
72
  // Route info automatically captured
73
  const user = getUserById(req.params.id);
74
  res.json(user);
75
});
76

77
// Error handler should be last middleware
78
app.use((err, req, res, next) => {
79
  console.error(err.stack);
80
  res.status(500).send("Something broke!");
81
});
82
```
83

84
### Fastify Integration
85

86
Automatic instrumentation and error handling for Fastify applications.
87

88
```typescript { .api }
89
/**
90
 * Create Fastify integration for automatic instrumentation
91
 * @param options - Fastify integration configuration options
92
 * @returns Fastify integration instance
93
 */
94
function fastifyIntegration(options?: FastifyOptions): Integration;
95

96
/**
97
 * Setup Fastify error handler
98
 * @param app - Fastify instance
99
 * @param options - Error handler configuration options
100
 */
101
function setupFastifyErrorHandler(app: FastifyInstance, options?: FastifyErrorHandlerOptions): void;
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
import * as Sentry from "@sentry/node";
108
import Fastify from "fastify";
109

110
// Initialize with Fastify integration
111
Sentry.init({
112
  dsn: "YOUR_DSN",
113
  integrations: [
114
    Sentry.fastifyIntegration({
115
      extractRequestData: ["headers", "method", "url", "query_string"],
116
    }),
117
  ],
118
});
119

120
const fastify = Fastify({ logger: true });
121

122
// Setup error handler
123
Sentry.setupFastifyErrorHandler(fastify, {
124
  shouldHandleError: (error) => error.statusCode >= 500,
125
});
126

127
// Register routes
128
fastify.get("/users/:id", async (request, reply) => {
129
  // Route automatically traced
130
  const user = await getUserById(request.params.id);
131
  return user;
132
});
133

134
// Error handling
135
fastify.setErrorHandler(async (error, request, reply) => {
136
  // Errors automatically captured by Sentry
137
  reply.status(500).send({ error: "Internal Server Error" });
138
});
139

140
const start = async () => {
141
  try {
142
    await fastify.listen({ port: 3000 });
143
  } catch (err) {
144
    fastify.log.error(err);
145
    process.exit(1);
146
  }
147
};
148
start();
149
```
150

151
### Koa.js Integration
152

153
Automatic instrumentation and error handling for Koa.js applications.
154

155
```typescript { .api }
156
/**
157
 * Create Koa.js integration for automatic instrumentation
158
 * @param options - Koa integration configuration options
159
 * @returns Koa integration instance
160
 */
161
function koaIntegration(options?: KoaOptions): Integration;
162

163
/**
164
 * Setup Koa error handler
165
 * @param app - Koa application instance
166
 * @param options - Error handler configuration options
167
 */
168
function setupKoaErrorHandler(app: KoaApp, options?: KoaErrorHandlerOptions): void;
169
```
170

171
**Usage Examples:**
172

173
```typescript
174
import * as Sentry from "@sentry/node";
175
import Koa from "koa";
176
import Router from "@koa/router";
177

178
// Initialize with Koa integration
179
Sentry.init({
180
  dsn: "YOUR_DSN",
181
  integrations: [
182
    Sentry.koaIntegration({
183
      extractRequestData: ["headers", "method", "url", "query"],
184
    }),
185
  ],
186
});
187

188
const app = new Koa();
189
const router = new Router();
190

191
// Setup error handler
192
Sentry.setupKoaErrorHandler(app, {
193
  shouldHandleError: (error) => error.status >= 500,
194
});
195

196
// Error handling middleware
197
app.on("error", (err, ctx) => {
198
  // Errors automatically captured by Sentry
199
  console.error("Server error:", err, ctx);
200
});
201

202
// Routes
203
router.get("/users/:id", async (ctx) => {
204
  // Route automatically traced
205
  const user = await getUserById(ctx.params.id);
206
  ctx.body = user;
207
});
208

209
app.use(router.routes()).use(router.allowedMethods());
210

211
app.listen(3000);
212
```
213

214
### Hapi.js Integration
215

216
Automatic instrumentation and error handling for Hapi.js applications.
217

218
```typescript { .api }
219
/**
220
 * Create Hapi.js integration for automatic instrumentation
221
 * @param options - Hapi integration configuration options
222
 * @returns Hapi integration instance
223
 */
224
function hapiIntegration(options?: HapiOptions): Integration;
225

226
/**
227
 * Setup Hapi error handler
228
 * @param server - Hapi server instance
229
 * @param options - Error handler configuration options
230
 */
231
function setupHapiErrorHandler(server: HapiServer, options?: HapiErrorHandlerOptions): void;
232
```
233

234
**Usage Examples:**
235

236
```typescript
237
import * as Sentry from "@sentry/node";
238
import Hapi from "@hapi/hapi";
239

240
// Initialize with Hapi integration
241
Sentry.init({
242
  dsn: "YOUR_DSN",
243
  integrations: [
244
    Sentry.hapiIntegration({
245
      extractRequestData: ["headers", "method", "url", "query"],
246
    }),
247
  ],
248
});
249

250
const init = async () => {
251
  const server = Hapi.server({
252
    port: 3000,
253
    host: "localhost",
254
  });
255

256
  // Setup error handler
257
  Sentry.setupHapiErrorHandler(server, {
258
    shouldHandleError: (error) => error.output?.statusCode >= 500,
259
  });
260

261
  // Route
262
  server.route({
263
    method: "GET",
264
    path: "/users/{id}",
265
    handler: async (request, h) => {
266
      // Route automatically traced
267
      const user = await getUserById(request.params.id);
268
      return user;
269
    },
270
  });
271

272
  // Error handling
273
  server.ext("onPreResponse", (request, h) => {
274
    const response = request.response;
275
    if (response.isBoom && response.output.statusCode >= 500) {
276
      // Error automatically captured by Sentry
277
      console.error("Server error:", response);
278
    }
279
    return h.continue;
280
  });
281

282
  await server.start();
283
  console.log("Server running on %s", server.info.uri);
284
};
285

286
init();
287
```
288

289
### Connect Middleware Integration
290

291
Automatic instrumentation for Connect middleware.
292

293
```typescript { .api }
294
/**
295
 * Create Connect integration for automatic instrumentation
296
 * @param options - Connect integration configuration options
297
 * @returns Connect integration instance
298
 */
299
function connectIntegration(options?: ConnectOptions): Integration;
300

301
/**
302
 * Setup Connect error handler
303
 * @param app - Connect app instance
304
 * @param options - Error handler configuration options
305
 */
306
function setupConnectErrorHandler(app: ConnectApp, options?: ConnectErrorHandlerOptions): void;
307
```
308

309
**Usage Examples:**
310

311
```typescript
312
import * as Sentry from "@sentry/node";
313
import connect from "connect";
314

315
// Initialize with Connect integration
316
Sentry.init({
317
  dsn: "YOUR_DSN",
318
  integrations: [
319
    Sentry.connectIntegration({
320
      extractRequestData: ["headers", "method", "url"],
321
    }),
322
  ],
323
});
324

325
const app = connect();
326

327
// Setup error handler
328
Sentry.setupConnectErrorHandler(app, {
329
  shouldHandleError: (error) => true,
330
});
331

332
// Middleware
333
app.use("/api", (req, res, next) => {
334
  // Request automatically traced
335
  if (req.url === "/users") {
336
    res.end("Users endpoint");
337
  } else {
338
    next();
339
  }
340
});
341

342
// Error middleware
343
app.use((err, req, res, next) => {
344
  // Errors automatically captured
345
  res.statusCode = 500;
346
  res.end("Internal Server Error");
347
});
348

349
app.listen(3000);
350
```
351

352
### HTTP Integration
353

354
General HTTP instrumentation for outgoing requests.
355

356
```typescript { .api }
357
/**
358
 * Create HTTP integration for outgoing request instrumentation
359
 * @param options - HTTP integration configuration options
360
 * @returns HTTP integration instance
361
 */
362
function httpIntegration(options?: HttpIntegrationOptions): Integration;
363

364
/**
365
 * Create Node.js fetch integration for fetch API instrumentation
366
 * @param options - Node fetch configuration options
367
 * @returns Node fetch integration instance
368
 */
369
function nativeNodeFetchIntegration(options?: NodeFetchOptions): Integration;
370
```
371

372
**Usage Examples:**
373

374
```typescript
375
import * as Sentry from "@sentry/node";
376

377
// Initialize with HTTP integrations
378
Sentry.init({
379
  dsn: "YOUR_DSN",
380
  integrations: [
381
    Sentry.httpIntegration({
382
      breadcrumbs: true, // Add breadcrumbs for HTTP requests
383
      tracing: true, // Create spans for HTTP requests
384
    }),
385
    Sentry.nativeNodeFetchIntegration({
386
      breadcrumbs: true,
387
      tracing: true,
388
    }),
389
  ],
390
});
391

392
// HTTP requests will be automatically traced
393
import http from "http";
394
import https from "https";
395

396
// This request will create a span
397
const req = https.request("https://api.example.com/data", (res) => {
398
  let data = "";
399
  res.on("data", (chunk) => {
400
    data += chunk;
401
  });
402
  res.on("end", () => {
403
    console.log("Response:", data);
404
  });
405
});
406
req.end();
407

408
// Fetch requests will also be traced
409
fetch("https://api.example.com/users")
410
  .then((response) => response.json())
411
  .then((data) => console.log(data));
412
```
413

414
## Types
415

416
### Integration Options
417

418
```typescript { .api }
419
interface ExpressOptions {
420
  /** Include router information in spans */
421
  router?: boolean;
422
  /** User properties to extract from req.user */
423
  user?: string[] | boolean;
424
  /** Request data to extract */
425
  extractRequestData?: string[];
426
}
427

428
interface ExpressErrorHandlerOptions {
429
  /** Function to determine if error should be handled */
430
  shouldHandleError?: (error: any) => boolean;
431
  /** Additional data to attach to events */
432
  attachEventData?: (event: Event, request: Request) => Event;
433
}
434

435
interface FastifyOptions {
436
  /** Request data to extract */
437
  extractRequestData?: string[];
438
}
439

440
interface FastifyErrorHandlerOptions {
441
  /** Function to determine if error should be handled */
442
  shouldHandleError?: (error: any) => boolean;
443
}
444

445
interface KoaOptions {
446
  /** Request data to extract */
447
  extractRequestData?: string[];
448
}
449

450
interface KoaErrorHandlerOptions {
451
  /** Function to determine if error should be handled */
452
  shouldHandleError?: (error: any) => boolean;
453
}
454

455
interface HapiOptions {
456
  /** Request data to extract */
457
  extractRequestData?: string[];
458
}
459

460
interface HapiErrorHandlerOptions {
461
  /** Function to determine if error should be handled */
462
  shouldHandleError?: (error: any) => boolean;
463
}
464

465
interface ConnectOptions {
466
  /** Request data to extract */
467
  extractRequestData?: string[];
468
}
469

470
interface ConnectErrorHandlerOptions {
471
  /** Function to determine if error should be handled */
472
  shouldHandleError?: (error: any) => boolean;
473
}
474
```
475

476
### HTTP Integration Options
477

478
```typescript { .api }
479
interface HttpIntegrationOptions {
480
  /** Add breadcrumbs for HTTP requests */
481
  breadcrumbs?: boolean;
482
  /** Create spans for HTTP requests */
483
  tracing?: boolean;
484
  /** URL patterns to ignore */
485
  ignoreUrls?: (string | RegExp)[];
486
  /** HTTP status codes to consider as errors */
487
  failedRequestStatusCodes?: [number, number][];
488
  /** HTTP status codes for successful requests */
489
  successfulRequestStatusCodes?: [number, number][];
490
}
491

492
interface NodeFetchOptions {
493
  /** Add breadcrumbs for fetch requests */
494
  breadcrumbs?: boolean;
495
  /** Create spans for fetch requests */
496
  tracing?: boolean;
497
  /** URL patterns to ignore */
498
  ignoreUrls?: (string | RegExp)[];
499
  /** HTTP status codes to consider as errors */
500
  failedRequestStatusCodes?: [number, number][];
501
  /** HTTP status codes for successful requests */
502
  successfulRequestStatusCodes?: [number, number][];
503
}
504
```
505

506
### Framework Types
507

508
```typescript { .api }
509
type RequestHandler = (req: any, res: any, next: any) => void;
510
type Express = any; // Express application instance
511
type FastifyInstance = any; // Fastify instance
512
type KoaApp = any; // Koa application instance
513
type HapiServer = any; // Hapi server instance
514
type ConnectApp = any; // Connect application instance
515
```