Node.js
Learn how to manually set up Sentry in your Node.js app and capture your first errors.
You need:
Choose the features you want to configure, and this guide will show you how:
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
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.jsconst 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,
});
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.
Which module system are you using?
The method for applying instrumentation depends on whether your application uses CommonJS (CJS) or ECMAScript Modules (ESM). If you're unsure which system you're using or if you're looking for alternative installation methods, see here.
Require the instrument.js file before any other modules:
app.js// Require this first!
require("./instrument");
// Now require other modules
const http = require("http");
// Your application code goes here
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
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
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:
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:
Sentry.startSpan(
{
op: "test",
name: "My First Test Transaction",
},
() => {
setTimeout(() => {
try {
foo();
} catch (e) {
Sentry.captureException(e);
}
}, 99);
},
);
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).
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
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").