Sentry for Node.js

Learn how to manually set up Sentry in your Node.js app and capture your first errors.

Agent-Assisted Setup

Use curl to download, read and follow https://skills.sentry.dev/instrument to set up the Sentry Node.js SDK.

Your agent will set up Sentry in your Node.js app automatically. Works with Cursor, Claude Code, Codex, and more.View docs ↗

Install the full plugin

Install the Sentry plugin to give your assistant every skill. See the installation docs for more details.

Copied

npx @sentry/agent-plugin install

You need:

A Sentry account and project
Your application up and running
Node version 20.19.0 or above. Node.js 22 needs 22.12 or higher, while Node.js 23 needs 23.2 or higher (>=20.19.0 <22.0.0 || >=22.12.0 <23.0.0 || >=23.2.0).

Choose the features you want to configure, and this guide will show you how:

Error MonitoringTracingProfiling

Want to learn more about these features?

Issues (always enabled): Sentry's core error monitoring product that automatically reports errors, uncaught exceptions, and unhandled rejections. If you have something that looks like an exception, Sentry can capture it.
Tracing: Track software performance while seeing the impact of errors across multiple systems. For example, distributed tracing allows you to follow a request from the frontend to the backend and back.
Profiling: Gain deeper insight than traditional tracing without custom instrumentation, letting you discover slow-to-execute or resource-intensive functions in your app.
Logs: Centralize and analyze your application logs to correlate them with errors and performance issues. Search, filter, and visualize log data to understand what's happening in your applications.
Application Metrics (always enabled): Track and analyze custom application metrics, such as response times and database query durations, to understand trends and patterns in your application's performance and behavior over time.

Run the command for your preferred package manager to add the Sentry SDK to your application:

Copied

npm install @sentry/node

npm install @sentry/node

yarn add @sentry/node

pnpm add @sentry/node

Copied

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

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

yarn add @sentry/node @sentry/profiling-node

pnpm add @sentry/node @sentry/profiling-node

To import and initialize Sentry, create a file named instrument.(js|mjs) in the root directory of your project and add the following code:

instrument.js

Copied

const Sentry = require("@sentry/node");
// ___PRODUCT_OPTION_START___ profiling
const { nodeProfilingIntegration } = require("@sentry/profiling-node");
// ___PRODUCT_OPTION_END___ profiling

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  // ___PRODUCT_OPTION_START___ profiling

  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  // ___PRODUCT_OPTION_END___ profiling
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#tracesSampleRate
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ profiling

  // Enable profiling for a percentage of sessions
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate
  profileSessionSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ profiling
});

const Sentry = require("@sentry/node");
// ___PRODUCT_OPTION_START___ profiling
const { nodeProfilingIntegration } = require("@sentry/profiling-node");
// ___PRODUCT_OPTION_END___ profiling

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  // ___PRODUCT_OPTION_START___ profiling

  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  // ___PRODUCT_OPTION_END___ profiling
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#tracesSampleRate
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ profiling

  // Enable profiling for a percentage of sessions
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate
  profileSessionSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ profiling
});

import * as Sentry from "@sentry/node";
// ___PRODUCT_OPTION_START___ profiling
import { nodeProfilingIntegration } from "@sentry/profiling-node";
// ___PRODUCT_OPTION_END___ profiling

// Ensure to call this before importing any other modules!
Sentry.init({
  dsn: "___PUBLIC_DSN___",

  // ___PRODUCT_OPTION_START___ profiling

  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  // ___PRODUCT_OPTION_END___ profiling
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#tracesSampleRate
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ profiling

  // Enable profiling for a percentage of sessions
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate
  profileSessionSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ profiling
});

Then, use the --import command line option and point it to your instrument.(js|mjs) file to load the module before the application starts:

Copied

node --import ./instrument.js app.js

node --import ./instrument.js app.js

node --import ./instrument.mjs app.mjs

If you are using a bundler like vite, you can also follow the bundler setup docs instead.

The stack traces in your Sentry errors probably won't look like your actual code without unminifying them. To fix this, upload your source maps to Sentry. The easiest way to do this is by using the Sentry Wizard.

Alternatively, take a look at our Uploading Source Maps documentation.

Copied

npx @sentry/wizard@latest -i sourcemaps

npx @sentry/wizard@latest -i sourcemaps

By default, the SDK sends user identity data (IP address, ID, and similar) and other data like HTTP bodies and URL query parameters. This will give you rich debugging context.

The SDK always filters sensitive values whose keys match a built-in denylist, such as auth or password, and sends [Filtered] instead.

To send less data, turn off the categories you don't need in the dataCollection option. For the full list of categories and their defaults, see the dataCollection options.

Copied

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  dataCollection: {
    userInfo: false,
    // other categories
  },
});

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  dataCollection: {
    userInfo: false,
    // other categories
  },
});

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following code snippet to your main application file, which will call an undefined function, triggering an error that Sentry will capture:

Copied

setTimeout(() => {
  try {
    foo();
  } catch (e) {
    Sentry.captureException(e);
  }
}, 99);

setTimeout(() => {
  try {
    foo();
  } catch (e) {
    Sentry.captureException(e);
  }
}, 99);

To test your tracing configuration, update the previous code snippet by starting a performance trace to measure the time it takes for the execution of your code:

Copied

Sentry.startSpan(
  {
    op: "test",
    name: "My First Test Transaction",
  },
  () => {
    setTimeout(() => {
      try {
        foo();
      } catch (e) {
        Sentry.captureException(e);
      }
    }, 99);
  },
);

Sentry.startSpan(
  {
    op: "test",
    name: "My First Test Transaction",
  },
  () => {
    setTimeout(() => {
      try {
        foo();
      } catch (e) {
        Sentry.captureException(e);
      }
    }, 99);
  },
);

To verify that Sentry catches your logs, add some log statements to your application:

Copied

Sentry.logger.info("User example action completed");

Sentry.logger.warn("Slow operation detected", {
  operation: "data_fetch",
  duration: 3500,
});

Sentry.logger.error("Validation failed", {
  field: "email",
  reason: "Invalid email",
});

Sentry.logger.info("User example action completed");

Sentry.logger.warn("Slow operation detected", {
  operation: "data_fetch",
  duration: 3500,
});

Sentry.logger.error("Validation failed", {
  field: "email",
  reason: "Invalid email",
});

Application Metrics are enabled by default.

Send test metrics from your app to verify that metrics are arriving in Sentry:

In a Node.js runtime, you can use the NodeRuntimeMetrics integration to automatically collect Node.js runtime health metrics.

Copied

Sentry.metrics.count("checkout.failed", 1);
Sentry.metrics.gauge("queue.depth", 42);
Sentry.metrics.distribution("api_latency", 187, {
  unit: "millisecond",
});

Sentry.metrics.count("checkout.failed", 1);
Sentry.metrics.gauge("queue.depth", 42);
Sentry.metrics.distribution("api_latency", 187, {
  unit: "millisecond",
});

Finally, head over to your project on Sentry.io to view the collected data (it takes a couple of moments for the data to appear).

Need help locating the captured errors in your Sentry project?

Open the Issues page and select an error from the issues list to view the full details and context of this error. For more details, see the Issue Details documentation.
Open the Traces page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click here.
Open the Profiles page, select a transaction, and then a profile ID to view its flame graph. For more information, click here.
Open the Logs page and filter by service, environment, or search keywords to view log entries from your application. For an interactive UI walkthrough, click here.
Open the Application Metrics page to view and analyze your metrics. For more details, see this interactive walkthrough.

At this point, you should have integrated Sentry into your application, which should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:

Explore practical guides on what to monitor, log, track, and investigate after setup
Extend Sentry to your frontend using one of our frontend SDKs
Learn how to manually capture errors
Continue to customize your configuration
Get familiar with Sentry's product features like tracing, insights, and alerts

Are you having problems setting up the SDK?

Check out alternative installation methods
Find various topics in Troubleshooting
Get support

Was this helpful?

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").

How to contribute | Edit this page | Create a docs issue | Get support