Node.js SDK

For Node.js applications, including Express, Fastify, Koa, and other frameworks.

Installation#

npm install @sentry/node

Setup#

Initialize at the very top of your entry file, before importing anything else:

import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: 'https://your-key@your-hostname.tindra.sh/1',
  environment: process.env.NODE_ENV,
  release: process.env.npm_package_version,
  tracesSampleRate: 0.1,
});

The order matters. Sentry must be initialized before other imports to instrument them correctly.

Express#

import express from 'express';
import * as Sentry from '@sentry/node';

Sentry.init({ dsn: '...' });

const app = express();

// Request handler must be the first middleware
app.use(Sentry.Handlers.requestHandler());

// Your routes
app.get('/', (req, res) => {
  res.send('Hello');
});

// Error handler must be before other error handlers
app.use(Sentry.Handlers.errorHandler());

Manual error capturing#

try {
  await processOrder(order);
} catch (error) {
  Sentry.captureException(error);
  throw error;
}

User context#

Use a stable application ID to follow the same user across errors, logs, and traces. Email is optional; keep the identity consistent between related applications.

Sentry.setUser({
  id: req.user.id,
  email: req.user.email,
});

Set this in middleware after authentication, inside the SDK's request isolation scope. Clear it on logout or when the current context becomes anonymous:

Sentry.setUser(null);

Do not store a request's user in a shared global scope; concurrent requests must keep separate identities. See the JavaScript SDK user API.

Custom spans#

const span = Sentry.startSpan({ op: 'db.query', name: 'Fetch user orders' }, async () => {
  return db.query('SELECT * FROM orders WHERE user_id = ?', [userId]);
});

Performance monitoring#

Automatic instrumentation covers:

• HTTP request/response timing
• Database queries (Postgres via pg, MySQL via mysql2, etc.)
• Redis commands (ioredis, redis)
• Outbound HTTP requests (http, https, fetch)

Profiling#

npm install @sentry/profiling-node

The @sentry/profiling-node version must match your @sentry/node version exactly.

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

Sentry.init({
  dsn: 'https://your-key@your-hostname.tindra.sh/1',
  integrations: [nodeProfilingIntegration()],
  tracesSampleRate: 0.1,
  profileSessionSampleRate: 1.0,
  profileLifecycle: 'trace',
});

See Profiling.

Testing#

Sentry.captureException(new Error('Hello Tindra'));

Check your dashboard. The event should appear within a few seconds.

Verify project setup#

After configuring the SDK, open Check setup for your project in Settings > Projects. Start a fresh check and capture an exception with the displayed tindra_setup tag, then wait for confirmed storage. The Project Setup guide covers generated browser/Node.js snippets, other SDKs, missing data, and optional transaction, profile, and source-map checks.