Express

Learn how to instrument the Sentry Express SDK.

This guide explains how to set up Sentry in your Express application.

Copied
npm install @sentry/node @sentry/profiling-node --save

Sentry should be initialized in your application as early as possible:

instrument.js
Copied
const express = require('express');
const Sentry = require('@sentry/node');
const { nodeProfilingIntegration } = require("@sentry/profiling-node");

const app = express();

// Sentry must be initialized as early as possible
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // Add Performance Monitoring by setting tracesSampleRate and adding integration
  // Set tracesSampleRate to 1.0 to capture 100% of transactions
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
  tracesSampleRate: 1.0,

  // Set sampling rate for profiling
  // This is relative to tracesSampleRate
  profilesSampleRate: 1.0,

  integrations: [
    expressIntegration({ app }),
    nodeProfilingIntegration(),
  ],

  // It is possible to specify the routes that should be traced by passing a router instance to the `router` option:
  // expressIntegration({ router: someRouterInstance })
});

// The Sentry request handler middleware must be added before any other handlers
app.use(Sentry.Handlers.requestHandler());
// Performance Monitoring: Create spans and traces for every incoming request
app.use(Sentry.Handlers.tracingHandler());

// All controllers should live here
app.get("/", function rootHandler(req, res) {
  res.end("Hello world!");
});

// The Sentry error handler middleware must be registered before any other error middleware and after all controllers
app.use(Sentry.Handlers.errorHandler());

// Optional fallthrough error handler
app.use(function onError(err, req, res, next) {
  // The ID of error events captured by the Sentry error middleware is attached to `res.sentry`.
  // You can use this ID for debugging, or to correlate requests with errors in Sentry.
  res.statusCode = 500;
  res.end(res.sentry + "\n");
});

app.listen(3000);

You can verify the Sentry integration by creating a route that will throw an error:

Copied
app.get("/debug-sentry", function mainHandler(req, res) {
  throw new Error("My first Sentry error!");
});

requestHandler accepts some options that let you decide which data should be included in the events that are sent to Sentry.

Possible options are:

Copied
// keys to be extracted from req
request?: boolean | string[]; // default: true = ['cookies', 'data', 'headers', 'method', 'query_string', 'url']

// server name
serverName?: boolean; // default: true

// generate transaction name
//   path == request.path (eg. "/foo")
//   methodPath == request.method + request.path (eg. "GET|/foo")
//   handler == function name (eg. "fooHandler")
transaction?: boolean | 'path' | 'methodPath' | 'handler'; // default: true = 'methodPath'

// keys to be extracted from req.user
user?: boolean | string[]; // default: true = ['id', 'username', 'email']

// client ip address
ip?: boolean; // default: false

// node version
version?: boolean; // default: true

// timeout for fatal route errors to be delivered
flushTimeout?: number; // default: undefined

If you want to skip the server name and just add the user, you would use requestHandler like this:

Copied
app.use(
  Sentry.Handlers.requestHandler({
    serverName: false,
    user: ["email"],
  }),
);

By default, errorHandler will only capture errors with a status code of 500 or higher. If you want to change it, provide it with the shouldHandleError callback, which accepts middleware errors as its argument and decides whether an error should be sent or not by returning an appropriate boolean value.

Copied
app.use(
  Sentry.Handlers.errorHandler({
    shouldHandleError(error) {
      // Capture all 404 and 500 errors
      if (error.status === 404 || error.status === 500) {
        return true;
      }
      return false;
    },
  }),
);

You can monitor the performance of your Express application by setting a tracesSampleRate, adding the expressIntegration, and registering the tracingHandler middleware.

Spans will then be created for the following operations:

  • HTTP requests made with request
  • get calls using native http and https modules
  • Middleware (Express.js only)

When capturing errors locally, ensure that your project's data filter for filtering localhost events is toggled off:

Issue alert

This ensures that errors produced by your browser (such as HTTP-method errors) are properly captured.

Previous
Welcome to Sentry
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").