Node.js

Prerequisites

You need:

• A Sentry account and project
• Your application up and running

Step 1: Install

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

Install the Sentry SDK

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

npm install @sentry/node

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

Step 2: Configure

Initialize the Sentry SDK

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

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

// Ensure to call this before requiring any other modules!
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],

  // 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,

  // Set profilesSampleRate to 1.0 to profile 100%
  // of sampled transactions.
  // This is relative to tracesSampleRate
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#profilesSampleRate
  profilesSampleRate: 1.0,
});

Apply Instrumentation to Your App

Make sure to initialize Sentry before you require or import any other modules in your app. Otherwise, auto-instrumentation won't work for these modules.

CommonJS

Require the instrument.js file before any other modules:

// Require this first!
require("./instrument");

// Now require other modules
const http = require("http");

// Your application code goes here

ESM

When running your application in ESM mode, use the --import command line option and point it to instrument.mjs to load the module before the application starts:

# Note: This is only available for Node v18.19.0 onwards.
node --import ./instrument.mjs app.mjs

Step 3: Add Readable Stack Traces With Source Maps (Optional)

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

npx @sentry/wizard@latest -i sourcemaps

Step 4: Verify Your Setup

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

Issues

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:

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);
  },
);

View Captured Data in Sentry

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

Next Steps

At this point, you should have integrated Sentry into your Node.js application and 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:

• 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