Sentry Node Sdk

All Skills > SDK Setup > Node.js / Bun / Deno SDK

Sentry Node.js / Bun / Deno SDK

Opinionated wizard that scans your project and guides you through complete Sentry setup for server-side JavaScript and TypeScript runtimes: Node.js, Bun, and Deno.

Invoke This Skill When

• User asks to "add Sentry to Node.js", "Bun", or "Deno"
• User wants to install or configure @sentry/node, @sentry/bun, or @sentry/deno
• User wants error monitoring, tracing, logging, profiling, crons, metrics, or AI monitoring for a backend JS/TS app
• User asks about instrument.js, --import ./instrument.mjs, bun --preload, or npm:@sentry/deno
• User wants to monitor Express, Fastify, Koa, Hapi, Connect, Bun.serve(), or Deno.serve()

NestJS? Use `sentry-nestjs-sdk` instead — it uses @sentry/nestjs with NestJS-native decorators and filters.

Next.js? Use `sentry-nextjs-sdk` instead — it handles the three-runtime architecture (browser, server, edge).

Note: SDK versions below reflect current Sentry docs at time of writing (@sentry/node ≥10.42.0, @sentry/bun ≥10.42.0, @sentry/deno ≥10.42.0).

Always verify against docs.sentry.io/platforms/javascript/guides/node/ before implementing.

---

Phase 1: Detect

Run these commands to identify the runtime, framework, and existing Sentry setup:

# Detect runtime
bun --version 2>/dev/null && echo "Bun detected"
deno --version 2>/dev/null && echo "Deno detected"
node --version 2>/dev/null && echo "Node.js detected"

# Detect existing Sentry packages
cat package.json 2>/dev/null | grep -E '"@sentry/'
cat deno.json deno.jsonc 2>/dev/null | grep -i sentry

# Detect Node.js framework
cat package.json 2>/dev/null | grep -E '"express"|"fastify"|"@hapi/hapi"|"koa"|"@nestjs/core"|"connect"'

# Detect Bun-specific frameworks
cat package.json 2>/dev/null | grep -E '"elysia"|"hono"'

# Detect Deno frameworks (deno.json imports)
cat deno.json deno.jsonc 2>/dev/null | grep -E '"oak"|"hono"|"fresh"'

# Detect module system (Node.js)
cat package.json 2>/dev/null | grep '"type"'
ls *.mjs *.cjs 2>/dev/null | head -5

# Detect existing instrument file
ls instrument.js instrument.mjs instrument.ts instrument.cjs 2>/dev/null

# Detect logging libraries
cat package.json 2>/dev/null | grep -E '"winston"|"pino"|"bunyan"'

# Detect cron / scheduling
cat package.json 2>/dev/null | grep -E '"node-cron"|"cron"|"agenda"|"bull"|"bullmq"'

# Detect AI / LLM usage
cat package.json 2>/dev/null | grep -E '"openai"|"@anthropic-ai"|"@langchain"|"@vercel/ai"|"@google/generative-ai"'

# Detect OpenTelemetry tracing
cat package.json 2>/dev/null | grep -E '"@opentelemetry/sdk-node"|"@opentelemetry/sdk-trace-node"|"@opentelemetry/sdk-trace-base"'
grep -rn "NodeTracerProvider\|trace\.getTracer\|startActiveSpan" \
  --include="*.ts" --include="*.js" --include="*.mjs" 2>/dev/null | head -5

# Check for companion frontend
ls frontend/ web/ client/ ui/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"vue"|"svelte"|"next"'

What to determine:

---

Phase 2: Recommend

Present a concrete recommendation based on what you found. Don't ask open-ended questions — lead with a proposal:

Route from OTel detection:

• OTel tracing detected (@opentelemetry/sdk-node or @opentelemetry/sdk-trace-node in package.json, or NodeTracerProvider in source) → use OTLP path: otlpIntegration() via @sentry/node-core/light; do not set tracesSampleRate; Sentry links errors to OTel traces automatically

Recommended (core coverage):

• ✅ Error Monitoring — always; captures unhandled exceptions, promise rejections, and framework errors
• ✅ Tracing — automatic HTTP, DB, and queue instrumentation via OpenTelemetry

Optional (enhanced observability):

• ⚡ Logging — structured logs via Sentry.logger.*; recommend when winston/pino/bunyan or log search is needed
• ⚡ Profiling — continuous CPU profiling (Node.js only; not available on Bun or Deno); not available with OTLP path
• ⚡ AI Monitoring — OpenAI, Anthropic, LangChain, Vercel AI SDK; recommend when AI/LLM calls detected
• ⚡ Crons — detect missed or failed scheduled jobs; recommend when node-cron, Bull, or Agenda is detected
• ⚡ Metrics — custom counters, gauges, distributions; recommend when custom KPIs needed
• ⚡ Runtime Metrics — automatic collection of memory, CPU, and event loop metrics; nodeRuntimeMetricsIntegration() (Node.js) / bunRuntimeMetricsIntegration() (Bun)

Recommendation logic:

OTel tracing detected: "I see OpenTelemetry tracing in the project. I recommend Sentry's OTLP integration for tracing (via your existing OTel setup) + Error Monitoring + Sentry Logging [+ Metrics/Crons/AI Monitoring if applicable]. Shall I proceed?"

No OTel: "I recommend setting up Error Monitoring + Tracing. Want me to also add Logging or Profiling?"

---

Phase 3: Guide

Runtime: Node.js

Option 1: Wizard (Recommended for Node.js)

You need to run this yourself — the wizard opens a browser for login and requires interactive input that the agent can't handle. Copy-paste into your terminal:

>

```

npx @sentry/wizard@latest -i node

```

>

It handles login, org/project selection, SDK installation, instrument.js creation, and package.json script updates.

>

Once it finishes, come back and skip to [Verification](#verification).

If the user skips the wizard, proceed with Option 2 (Manual Setup) below.

---

Option 2: Manual Setup — Node.js

Install

npm install @sentry/node --save
# or
yarn add @sentry/node
# or
pnpm add @sentry/node

Create the Instrument File

CommonJS (`instrument.js`):

// instrument.js — must be loaded before all other modules
const Sentry = require("@sentry/node");

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,

  // 100% in dev, lower in production
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // Capture local variable values in stack frames
  includeLocalVariables: true,

  enableLogs: true,
});

ESM (`instrument.mjs`):

// instrument.mjs — loaded via --import flag before any other module
import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  includeLocalVariables: true,
  enableLogs: true,
});

Start Your App with Sentry Loaded First

CommonJS — add require("./instrument") as the very first line of your entry file:

// app.js
require("./instrument"); // must be first

const express = require("express");
// ... rest of your app

ESM — use the --import flag so Sentry loads before all other modules (Node.js 18.19.0+ required):

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

Add to package.json scripts:

{
  "scripts": {
    "start": "node --import ./instrument.mjs server.mjs",
    "dev": "node --import ./instrument.mjs --watch server.mjs"
  }
}

Or via environment variable (useful for wrapping existing start commands):

NODE_OPTIONS="--import ./instrument.mjs" npm start

Framework Error Handlers

Register the Sentry error handler after all routes so it can capture framework errors:

Express:

const express = require("express");
const Sentry = require("@sentry/node");

const app = express();

// ... your routes

// Add AFTER all routes — captures 5xx errors by default
Sentry.setupExpressErrorHandler(app);

// Optional: capture 4xx errors too
// Sentry.setupExpressErrorHandler(app, {
//   shouldHandleError(error) { return error.status >= 400; },
// });

app.listen(3000);

Fastify:

const Fastify = require("fastify");
const Sentry = require("@sentry/node");

const fastify = Fastify();

// Add BEFORE routes (unlike Express!)
Sentry.setupFastifyErrorHandler(fastify);

// ... your routes

await fastify.listen({ port: 3000 });

Koa:

const Koa = require("koa");
const Sentry = require("@sentry/node");

const app = new Koa();

// Add as FIRST middleware (catches errors thrown by later middleware)
Sentry.setupKoaErrorHandler(app);

// ... your other middleware and routes

app.listen(3000);

Hapi (async — must await):

const Hapi = require("@hapi/hapi");
const Sentry = require("@sentry/node");

const server = Hapi.server({ port: 3000 });

// ... your routes

// Must await — Hapi registration is async
await Sentry.setupHapiErrorHandler(server);

await server.start();

Connect:

const connect = require("connect");
const Sentry = require("@sentry/node");

const app = connect();

// Add BEFORE routes (like Fastify and Koa)
Sentry.setupConnectErrorHandler(app);

// ... your middleware and routes

require("http").createServer(app).listen(3000);

NestJS — has its own dedicated skill with full coverage:

Use the [`sentry-nestjs-sdk`](../sentry-nestjs-sdk/SKILL.md) skill instead.

NestJS uses a separate package (@sentry/nestjs) with NestJS-native constructs:

SentryModule.forRoot(), SentryGlobalFilter, @SentryTraced, @SentryCron decorators,

and GraphQL/Microservices support. Load that skill for complete NestJS setup.

Vanilla Node.js `http` module — wrap request handler manually:

const http = require("http");
const Sentry = require("@sentry/node");

const server = http.createServer((req, res) => {
  Sentry.withIsolationScope(() => {
    try {
      // your handler
      res.end("OK");
    } catch (err) {
      Sentry.captureException(err);
      res.writeHead(500);
      res.end("Internal Server Error");
    }
  });
});

server.listen(3000);

Framework error handler summary:

---

Runtime: Bun

No wizard available for Bun. Manual setup only.

Install

bun add @sentry/bun

Create instrument.ts (or instrument.js)

// instrument.ts
import * as Sentry from "@sentry/bun";

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  enableLogs: true,
});

Start Your App with --preload

bun --preload ./instrument.ts server.ts

Add to package.json:

{
  "scripts": {
    "start": "bun --preload ./instrument.ts server.ts",
    "dev": "bun --watch --preload ./instrument.ts server.ts"
  }
}

Bun.serve() — Auto-Instrumentation

@sentry/bun automatically instruments Bun.serve() via JavaScript Proxy. No extra setup is required — just initialize with --preload and your Bun.serve() calls are traced:

// server.ts
const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun!");
  },
});

Framework Error Handlers on Bun

Bun can run Express, Fastify, Hono, and Elysia. Use the same @sentry/bun import and the @sentry/node error handler functions (re-exported by @sentry/bun):

import * as Sentry from "@sentry/bun";
import express from "express";

const app = express();
// ... routes
Sentry.setupExpressErrorHandler(app);
app.listen(3000);

Bun Feature Support

---

Runtime: Deno

No wizard available for Deno. Manual setup only.

Requires Deno 2.0+. Deno 1.x is not supported.

Use `npm:` specifier. The deno.land/x/sentry registry is deprecated.

Install via deno.json (Recommended)

{
  "imports": {
    "@sentry/deno": "npm:@sentry/deno@10.42.0"
  }
}

Or import directly with the npm: specifier:

import * as Sentry from "npm:@sentry/deno";

Initialize — Add to Entry File

// main.ts — Sentry.init() must be called before any other code
import * as Sentry from "@sentry/deno";

Sentry.init({
  dsn: Deno.env.get("SENTRY_DSN") ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: Deno.env.get("DENO_ENV") === "development" ? 1.0 : 0.1,
  enableLogs: true,
});

// Your application code follows
Deno.serve({ port: 8000 }, (req) => {
  return new Response("Hello from Deno!");
});

Unlike Node.js and Bun, Deno does not have a --preload or --import flag. Sentry must be the first import in your entry file.

Required Deno Permissions

The SDK requires network access to reach your Sentry ingest domain:

deno run \
  --allow-net=o<ORG_ID>.ingest.sentry.io \
  --allow-read=./src \
  --allow-env=SENTRY_DSN,SENTRY_RELEASE \
  main.ts

For development, --allow-all works but is not recommended for production.

Deno Cron Integration

Deno provides native cron scheduling. Use denoCronIntegration for automatic monitoring:

import * as Sentry from "@sentry/deno";
import { denoCronIntegration } from "@sentry/deno";

Sentry.init({
  dsn: Deno.env.get("SENTRY_DSN") ?? "___DSN___",
  integrations: [denoCronIntegration()],
});

// Cron is automatically monitored
Deno.cron("daily-cleanup", "0 0 * * *", () => {
  // cleanup logic
});

Deno Feature Support

---

OTLP Integration (OTel-First Projects — Node.js Only)

Use this path only when OpenTelemetry tracing was detected in Phase 1

(e.g., @opentelemetry/sdk-node or @opentelemetry/sdk-trace-node in package.json).

For projects without an existing OTel setup, use the standard @sentry/node path above.

The OTLP integration uses @sentry/node-core/light — a lightweight Sentry SDK that does not bundle its own OpenTelemetry. Instead, it hooks into the user's existing OTel TracerProvider and exports spans to Sentry via OTLP.

When to Use

Install

npm install @sentry/node-core @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base
# or
yarn add @sentry/node-core @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base
# or
pnpm add @sentry/node-core @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base

The @opentelemetry/* packages are peer dependencies. If the project already has them installed, skip duplicates.

Initialize

// instrument.mjs — load via --import flag before any other module
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import * as Sentry from '@sentry/node-core/light';
import { otlpIntegration } from '@sentry/node-core/light/otlp';

// Register the user's OTel TracerProvider first
const provider = new NodeTracerProvider();
provider.register();

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? '___DSN___',

  sendDefaultPii: true,
  enableLogs: true,

  // Do NOT set tracesSampleRate — OTel controls sampling
  integrations: [
    otlpIntegration({
      // Export OTel spans to Sentry via OTLP (default: true)
      setupOtlpTracesExporter: true,
    }),
  ],
});

With a custom Collector endpoint:

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? '___DSN___',
  integrations: [
    otlpIntegration({
      collectorUrl: 'http://localhost:4318/v1/traces',
    }),
  ],
});

Start Your App

Same --import pattern as the standard Node.js setup:

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

Key Differences from Standard @sentry/node

---

For Each Agreed Feature

Load the corresponding reference file and follow its steps:

For each feature: read the reference file, follow its steps exactly, and verify before moving on.

Runtime Metrics

Automatically collect Node.js and Bun runtime health metrics (memory, CPU utilization, event loop delay/utilization, uptime) at a configurable interval. Metrics appear in Sentry's Metrics product under the node.runtime.* / bun.runtime.* namespace.

Node.js — add nodeRuntimeMetricsIntegration() to your instrument.js:

const Sentry = require("@sentry/node");

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  integrations: [
    Sentry.nodeRuntimeMetricsIntegration(),
    // Optional: change collection interval (default 30 000 ms)
    // Sentry.nodeRuntimeMetricsIntegration({ collectionIntervalMs: 60_000 }),
  ],
});

Metrics collected by default: node.runtime.mem.rss, node.runtime.mem.heap_used, node.runtime.mem.heap_total, node.runtime.cpu.utilization, node.runtime.event_loop.delay.p50, node.runtime.event_loop.delay.p99, node.runtime.event_loop.utilization, node.runtime.process.uptime.

Bun — add bunRuntimeMetricsIntegration() to your instrument.ts:

import * as Sentry from "@sentry/bun";
import { bunRuntimeMetricsIntegration } from "@sentry/bun";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  integrations: [
    bunRuntimeMetricsIntegration(),
    // Optional: change collection interval (default 30 000 ms)
    // bunRuntimeMetricsIntegration({ collectionIntervalMs: 60_000 }),
  ],
});

Metrics collected: same as Node.js except no event loop delay percentiles (unavailable in Bun). Prefixed with bun.runtime.*.

---

Verification

After setup, verify Sentry is receiving events:

// Add temporarily to your entry file or a test route, then remove
import * as Sentry from "@sentry/node"; // or @sentry/bun / @sentry/deno

Sentry.captureException(new Error("Sentry test error — delete me"));

Or trigger an unhandled exception:

// In a route handler or startup — will be captured automatically
throw new Error("Sentry test error — delete me");

Then check your Sentry Issues dashboard — the error should appear within ~30 seconds.

Verification checklist:

---

Config Reference

Sentry.init() Core Options

nativeNodeFetchIntegration() Options

Configures outgoing fetch/undici span capture. Since @opentelemetry/instrumentation-undici@0.22.0, response headers like content-length are no longer captured automatically — use headersToSpanAttributes to opt in:

Sentry.init({
  integrations: [
    Sentry.nativeNodeFetchIntegration({
      headersToSpanAttributes: {
        requestHeaders: ["x-request-id"],
        responseHeaders: ["content-length", "content-type"],
      },
    }),
  ],
});

otlpIntegration() Options (@sentry/node-core/light/otlp)

For OTel-first projects using @sentry/node-core/light. Import: import { otlpIntegration } from '@sentry/node-core/light/otlp'.

Graceful Shutdown

Flush buffered events before process exit — important for short-lived scripts and serverless:

process.on("SIGTERM", async () => {
  await Sentry.close(2000); // flush with 2s timeout
  process.exit(0);
});

Environment Variables

Source Maps (Node.js)

Readable stack traces in production require source map upload. Use @sentry/cli or the webpack/esbuild/rollup plugins:

npm install @sentry/cli --save-dev

# Create a Sentry auth token at sentry.io/settings/auth-tokens/
# Set in .env.sentry-build-plugin (gitignore this file):
SENTRY_AUTH_TOKEN=sntrys_eyJ...

Add upload step to your build:

{
  "scripts": {
    "build": "tsc && sentry-cli sourcemaps inject ./dist && sentry-cli sourcemaps upload ./dist"
  }
}

---

Phase 4: Cross-Link

After completing backend setup, check for companion services:

# Frontend companion
ls frontend/ web/ client/ ui/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"vue"|"svelte"|"next"'

# Other backend services
ls ../go.mod ../requirements.txt ../Gemfile 2>/dev/null

If a frontend, framework-specific SDK, or other backend is found, suggest the matching skill:

Dedicated JavaScript framework skills (prefer these over generic node-sdk):

Frontend companions:

Other backend companions:

Connecting frontend and backend with the same DSN or linked projects enables distributed tracing — stack traces that span your browser, API server, and database in a single trace view.

---

Troubleshooting

AI Monitoring - Sentry Node.js SDK

Minimum SDK: @sentry/node >=10.53.0. OpenAI, Anthropic, LangChain, LangGraph, Google GenAI, Vercel AI SDK auto-instrument.

Prerequisites

Tracing must be enabled - AI spans require an active trace:

Sentry.init({
  dsn: "...",
  tracesSampleRate: 1.0,
  streamGenAiSpans: true,
  sendDefaultPii: true,
});

Integration Matrix

*Vercel AI SDK requires experimental_telemetry: { isEnabled: true } on every call.

PII Control

Set sendDefaultPii: true in Sentry.init() to let supported integrations default recordInputs/recordOutputs to true. Use integration-level options to opt out or override specific integrations.

Configuration Examples

Auto-enabled integrations

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  streamGenAiSpans: true,
  sendDefaultPii: true, // required to capture prompts/outputs
});
// OpenAI, Anthropic, LangChain, LangGraph, Google GenAI activate automatically

Explicit configuration with recordInputs/recordOutputs override

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  streamGenAiSpans: true,
  sendDefaultPii: true,
  integrations: [
    Sentry.openAIIntegration(),
    Sentry.vercelAIIntegration(),
  ],
});

Vercel AI SDK per-call telemetry (required)

await generateText({
  model: openai("gpt-4.1"),
  prompt: "Hello",
  experimental_telemetry: { isEnabled: true, recordInputs: true, recordOutputs: true },
});

Browser / Next.js client-side (manual wrapping required)

import OpenAI from "openai";
import * as Sentry from "@sentry/nextjs"; // or @sentry/browser

const openai = Sentry.instrumentOpenAiClient(new OpenAI());

Manual Instrumentation - gen_ai.* Spans

Use when the library isn't supported, or for wrapping custom AI logic.

gen_ai.request - LLM call

await Sentry.startSpan({
  op: "gen_ai.request",
  name: "chat claude-sonnet-4-6",
  attributes: { "gen_ai.request.model": "claude-sonnet-4-6" },
}, async (span) => {
  span.setAttribute("gen_ai.request.messages", JSON.stringify(messages));
  const result = await myClient.chat(messages);
  span.setAttribute("gen_ai.usage.input_tokens", result.usage.inputTokens);
  span.setAttribute("gen_ai.usage.output_tokens", result.usage.outputTokens);
  return result;
});

gen_ai.invoke_agent - Agent lifecycle

await Sentry.startSpan({
  op: "gen_ai.invoke_agent",
  name: "invoke_agent Weather Agent",
  attributes: { "gen_ai.agent.name": "Weather Agent", "gen_ai.request.model": "claude-sonnet-4-6" },
}, async (span) => {
  const result = await myAgent.run(task);
  span.setAttribute("gen_ai.usage.input_tokens", result.totalInputTokens);
  span.setAttribute("gen_ai.usage.output_tokens", result.totalOutputTokens);
  return result;
});

gen_ai.execute_tool - Tool/function call

await Sentry.startSpan({
  op: "gen_ai.execute_tool",
  name: "execute_tool get_weather",
  attributes: {
    "gen_ai.tool.name": "get_weather",
    "gen_ai.tool.type": "function",
    "gen_ai.tool.input": JSON.stringify({ location: "Paris" }),
  },
}, async (span) => {
  const result = await getWeather("Paris");
  span.setAttribute("gen_ai.tool.output", JSON.stringify(result));
  return result;
});

Span Attribute Reference

Common attributes

Content attributes (PII-gated — only when sendDefaultPii: true + recordInputs/recordOutputs: true)

Span attributes only accept primitives - arrays/objects must be JSON-stringified.

Token usage attributes

Cached and reasoning tokens are subsets of totals, not additive. Incorrect reporting produces wrong cost calculations.

Agent Workflow Hierarchy

Transaction
└── gen_ai.invoke_agent  "Weather Agent"
    ├── gen_ai.request      "chat claude-sonnet-4-6"
    ├── gen_ai.execute_tool "get_weather"
    ├── gen_ai.request      "chat claude-sonnet-4-6"     ← follow-up
    └── gen_ai.execute_tool "format_report"

Streaming

Unsupported Providers

Sampling Strategy

If tracesSampleRate < 1.0, see the AI sampling guide.

Conversation Tracking

Link AI spans across turns into a chat-style timeline at Explore > Conversations.

Prerequisites: streamGenAiSpans: true (SDK >=10.53.0) and sendDefaultPii: true must be set — Conversations reconstructs the chat from input/output attributes, so without PII capture the view will be empty.

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

// Set at the start of a conversation
Sentry.setConversationId("conv_abc123");

// All subsequent AI calls carry gen_ai.conversation.id: "conv_abc123"
await openai.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Hello" }],
});

// Later turns in the same conversation are linked automatically
await openai.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    { role: "user", content: "Hello" },
    { role: "assistant", content: "Hi there!" },
    { role: "user", content: "What's the weather?" },
  ],
});

A single conversation can span multiple traces (e.g., page refresh), and a single trace can contain multiple conversations.

Troubleshooting

Crons / Job Monitoring — Sentry Node.js SDK

Minimum SDK: @sentry/node ≥7.51.1 (captureCheckIn, withMonitor)

instrumentNodeCron / instrumentCron: ≥7.92.0

instrumentNodeSchedule: ≥7.93.0

failureIssueThreshold / recoveryThreshold: ≥8.7.0

isolateTrace in MonitorConfig: ≥10.28.0

Status: ✅ Generally Available

---

Overview

Sentry Crons (job monitoring) tracks whether scheduled tasks run on time, succeed, and complete within expected durations. Sentry will alert when a job:

• Misses its scheduled start time (checkin margin exceeded)
• Takes too long to complete (maxRuntime exceeded)
• Fails (status "error")

---

Core API

Sentry.captureCheckIn(checkIn, monitorConfig?) → string

// Three check-in shapes:

// 1. Heartbeat — single-shot, no duration tracking
Sentry.captureCheckIn({ monitorSlug: "my-job", status: "ok" });
Sentry.captureCheckIn({ monitorSlug: "my-job", status: "error" });

// 2. In-progress — signals job started, returns ID for completion
const checkInId = Sentry.captureCheckIn({
  monitorSlug: "my-job",
  status: "in_progress",
});

// 3. Finished — completes an in-progress check-in
Sentry.captureCheckIn({
  checkInId,
  monitorSlug: "my-job",
  status: "ok",          // or "error"
  duration: 12.3,        // optional, in seconds
});

Sentry.withMonitor(slug, callback, monitorConfig?) → T

Wraps a sync or async function. Automatically sends in_progress, then ok on success or error on throw. Records duration automatically.

// Simple form
await Sentry.withMonitor("my-job", async () => {
  await runJob();
});

// With monitor config
await Sentry.withMonitor("my-job", async () => {
  await runJob();
}, {
  schedule: { type: "crontab", value: "0 * * * *" },
  checkinMargin: 5,
  maxRuntime: 30,
  timezone: "America/New_York",
});

---

Check-In Status Values

---

Usage Patterns

Heartbeat (simplest — detect missed runs only)

try {
  await runMyJob();
  Sentry.captureCheckIn({ monitorSlug: "my-cron-job", status: "ok" });
} catch (err) {
  Sentry.captureCheckIn({ monitorSlug: "my-cron-job", status: "error" });
  throw err;
}

Start/Finish (tracks in-progress state and duration)

const checkInId = Sentry.captureCheckIn({
  monitorSlug: "my-cron-job",
  status: "in_progress",
});

const startTime = Date.now();

try {
  await runMyJob();
  Sentry.captureCheckIn({
    checkInId,
    monitorSlug: "my-cron-job",
    status: "ok",
    duration: (Date.now() - startTime) / 1000,  // seconds
  });
} catch (err) {
  Sentry.captureCheckIn({
    checkInId,
    monitorSlug: "my-cron-job",
    status: "error",
    duration: (Date.now() - startTime) / 1000,
  });
  throw err;
}

withMonitor (recommended — handles all status logic)

await Sentry.withMonitor("my-cron-job", async () => {
  await runMyJob();
});

---

Monitor Configuration (Upsert)

Pass a MonitorConfig to create or update the monitor from code — no manual setup in Sentry UI needed. On first check-in the monitor is created; subsequent calls update it.

interface MonitorConfig {
  schedule: CrontabSchedule | IntervalSchedule;  // REQUIRED
  checkinMargin?: number;          // minutes: grace period before "missed" alert
  maxRuntime?: number;             // minutes: max execution before timeout alert
  timezone?: string;               // IANA timezone, e.g. "America/New_York"
  failureIssueThreshold?: number;  // consecutive failures before creating issue (≥8.7.0)
  recoveryThreshold?: number;      // consecutive OKs before resolving issue (≥8.7.0)
  isolateTrace?: boolean;          // new trace per monitor run (≥10.28.0)
}

Pass as the second argument to captureCheckIn() or third argument to withMonitor().

---

Schedule Types

Crontab schedule:

{ type: "crontab", value: "* * * * *" }          // every minute
{ type: "crontab", value: "0 * * * *" }          // every hour
{ type: "crontab", value: "0 4 * * *" }          // daily at 4:00am
{ type: "crontab", value: "0 9 * * MON-FRI" }    // weekdays at 9am
{ type: "crontab", value: "0 0 1 * *" }          // first of every month
{ type: "crontab", value: "*/15 * * * *" }       // every 15 minutes

Interval schedule:

{ type: "interval", value: 1,  unit: "hour" }
{ type: "interval", value: 30, unit: "minute" }
{ type: "interval", value: 7,  unit: "day" }
{ type: "interval", value: 1,  unit: "week" }
// unit: "year" | "month" | "week" | "day" | "hour" | "minute"

---

Full Upsert Example

const monitorConfig: Sentry.MonitorConfig = {
  schedule: {
    type: "crontab",
    value: "0 4 * * *",           // daily at 4am
  },
  checkinMargin: 5,               // alert if not started within 5 min
  maxRuntime: 30,                 // alert if running > 30 min
  timezone: "America/New_York",
  failureIssueThreshold: 3,       // create issue after 3 consecutive failures
  recoveryThreshold: 2,           // resolve issue after 2 consecutive successes
  isolateTrace: true,             // SDK ≥10.28.0
};

await Sentry.withMonitor("daily-report-job", generateDailyReport, monitorConfig);

---

Scheduler Library Integrations

node-cron (SDK ≥7.92.0)

import cron from "node-cron";
import * as Sentry from "@sentry/node";

const cronWithCheckIn = Sentry.cron.instrumentNodeCron(cron);

// `name` option is REQUIRED — becomes the monitor slug
cronWithCheckIn.schedule(
  "* * * * *",
  () => { /* task */ },
  { name: "my-cron-job" },
);

cron package — CronJob (SDK ≥7.92.0)

import { CronJob } from "cron";
import * as Sentry from "@sentry/node";

// Monitor slug is bound at instrumentation time
const CronJobWithCheckIn = Sentry.cron.instrumentCron(CronJob, "my-cron-job");

// Constructor form
const job = new CronJobWithCheckIn("* * * * *", () => { /* task */ });

// Static factory form
const job2 = CronJobWithCheckIn.from({
  cronTime: "* * * * *",
  onTick: () => { /* task */ },
});

node-schedule (SDK ≥7.93.0)

import * as schedule from "node-schedule";
import * as Sentry from "@sentry/node";

const scheduleWithCheckIn = Sentry.cron.instrumentNodeSchedule(schedule);

// First argument must be the job name (monitor slug)
scheduleWithCheckIn.scheduleJob(
  "my-cron-job",      // monitor slug — REQUIRED as first arg
  "* * * * *",        // cron expression
  () => { /* task */ },
);

Agenda (no official helper — use withMonitor)

import Agenda from "agenda";
import * as Sentry from "@sentry/node";

const agenda = new Agenda({ db: { address: "mongodb://localhost/agenda" } });

agenda.define("send-newsletter", async (job) => {
  await Sentry.withMonitor(
    "send-newsletter",
    async () => { await sendNewsletterEmails(); },
    {
      schedule: { type: "crontab", value: "0 8 * * MON" },
      maxRuntime: 60,
      timezone: "UTC",
    },
  );
});

Bull / BullMQ (no official helper — use withMonitor)

import { Worker } from "bullmq";
import * as Sentry from "@sentry/node";

const worker = new Worker("report-queue", async (job) => {
  await Sentry.withMonitor(
    "report-queue-processor",
    async () => { await processReportJob(job.data); },
    {
      schedule: { type: "interval", value: 5, unit: "minute" },
      maxRuntime: 10,
      checkinMargin: 2,
    },
  );
});

---

Library Integration Signatures

// node-cron
function instrumentNodeCron<T>(
  lib: Partial<NodeCron> & T,
  monitorConfig?: Pick<MonitorConfig, "isolateTrace">,
): T;

// cron package
function instrumentCron<T>(
  lib: T & CronJobConstructor,
  monitorSlug: string,    // REQUIRED — single slug for all jobs from this constructor
): T;

// node-schedule
function instrumentNodeSchedule<T>(
  lib: T & NodeSchedule,
): T;

---

Serverless / Lambda

Check-ins are lost if the process terminates before flush. Always flush explicitly:

export const handler = async (event: any) => {
  const checkInId = Sentry.captureCheckIn({
    monitorSlug: "lambda-scheduled-job",
    status: "in_progress",
  });

  try {
    await doWork(event);
    Sentry.captureCheckIn({
      checkInId,
      monitorSlug: "lambda-scheduled-job",
      status: "ok",
    });
  } catch (err) {
    Sentry.captureCheckIn({
      checkInId,
      monitorSlug: "lambda-scheduled-job",
      status: "error",
    });
    throw err;
  } finally {
    // CRITICAL — flush before Lambda container freezes
    await Sentry.flush(2000);
  }
};

For AWS Lambda, prefer @sentry/aws-serverless — it handles flushing automatically.

---

Deno: Native Cron Integration

Deno provides a built-in Deno.cron() API. Use denoCronIntegration to automatically monitor all native Deno crons:

import * as Sentry from "@sentry/deno";

Sentry.init({
  dsn: Deno.env.get("SENTRY_DSN"),
  integrations: [
    Sentry.denoCronIntegration(),
  ],
});

// Automatically monitored — no manual check-ins needed
Deno.cron("daily-cleanup", "0 0 * * *", async () => {
  await cleanupOldRecords();
});

Deno.cron("hourly-sync", "0 * * * *", async () => {
  await syncExternalData();
});

The integration intercepts Deno.cron() calls and wraps them with automatic in_progress → ok/error check-ins. The monitor slug is the first argument to Deno.cron().

Deno Deploy: Deno.cron() runs natively on Deno Deploy. The integration works in both local Deno and Deno Deploy environments.

Node.js and Bun: denoCronIntegration is only available in @sentry/deno. For Node.js, use the node-cron, cron, or node-schedule library helpers above.

---

Rate Limits

• Maximum 6 check-ins per minute per monitor + environment combination
• Each environment (production, staging, etc.) counts separately
• Dropped check-ins appear in Sentry's Usage Stats page

---

Troubleshooting

Error Monitoring — Sentry Node.js SDK

Minimum SDK: @sentry/node ≥8.0.0

NestJS integration: @sentry/nestjs ≥8.0.0

Bun integration: @sentry/bun ≥8.0.0 (thin wrapper over @sentry/node)

Deno integration: npm:@sentry/deno (Deno 2+)

---

The Instrument-First Rule

@sentry/node patches modules at import time via OpenTelemetry. The instrument file must be loaded before everything else — before your framework, before your database driver, before any HTTP client.

// instrument.js — loaded first
const Sentry = require("@sentry/node");

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  release: "my-app@1.2.3",
  environment: process.env.NODE_ENV ?? "production",
  tracesSampleRate: 1.0,
  sendDefaultPii: true,
});

// app.js
require("./instrument");  // MUST be line 1
const express = require("express");
// ...

ESM (Node 18.19+ / 19.9+):

// instrument.mjs
import * as Sentry from "@sentry/node";
Sentry.init({ dsn: "...", tracesSampleRate: 1.0 });

# Launch with --import
node --import ./instrument.mjs app.mjs
# or:
NODE_OPTIONS="--import ./instrument.mjs" npm start

---

What Is Captured Automatically

The Core Rule

"If you catch an error and don't re-throw it, Sentry never sees it."

// ✅ Auto-captured — unhandled, bubbles up
throw new Error("Unhandled");

// ✅ Auto-captured — re-thrown
try {
  await doSomething();
} catch (err) {
  throw err;
}

// ❌ NOT captured — swallowed by graceful return
try {
  await doSomething();
} catch (err) {
  return res.status(500).json({ error: "Failed" }); // ← add captureException!
}

// ✅ Manually captured
try {
  await doSomething();
} catch (err) {
  Sentry.captureException(err);
  return res.status(500).json({ error: "Failed" });
}

---

Framework Error Handler Placement

Critical: placement rules differ per framework. Getting this wrong silently misses errors.

---

Express

Error handler goes after all routes, before your own error handler.

require("./instrument");
const express = require("express");
const Sentry = require("@sentry/node");

const app = express();
app.use(express.json());

// ── Routes ──────────────────────────────────────────────────────
app.get("/", (req, res) => res.json({ ok: true }));
app.post("/orders", async (req, res, next) => {
  try {
    const result = await processOrder(req.body.orderId);
    res.json(result);
  } catch (err) {
    next(err); // pass to error handlers
  }
});

// ↓ Sentry AFTER routes, BEFORE your error handler
Sentry.setupExpressErrorHandler(app);

// Optional: capture only specific status codes
// Sentry.setupExpressErrorHandler(app, {
//   shouldHandleError(error) {
//     return !error.status || parseInt(String(error.status)) >= 500;
//   },
// });

// ── Your error handler (runs after Sentry) ──────────────────────
app.use((err, req, res, next) => {
  res.status(err.status || 500).json({ error: "Internal Server Error" });
});

app.listen(3000);

---

Fastify

Error handler goes before routes. Internally registers a Fastify plugin using onError lifecycle hook.

require("./instrument");
const Fastify = require("fastify");
const Sentry = require("@sentry/node");

const app = Fastify({ logger: true });

// ↓ Sentry BEFORE routes
Sentry.setupFastifyErrorHandler(app);

// Optional: customize which errors are captured
// Sentry.setupFastifyErrorHandler(app, {
//   shouldHandleError(error, request, reply) {
//     return reply.statusCode >= 500;
//   },
// });

app.get("/", async (request, reply) => ({ hello: "world" }));
app.get("/debug-sentry", async () => {
  throw new Error("Test Fastify error!");
});

app.listen({ port: 3000 });

---

Koa

Error handler goes as the first `app.use()` call, before any route.

require("./instrument");
const Koa = require("koa");
const Router = require("@koa/router");
const Sentry = require("@sentry/node");

const app = new Koa();
const router = new Router();

// ↓ Sentry FIRST middleware
Sentry.setupKoaErrorHandler(app);

router.get("/", async (ctx) => { ctx.body = { ok: true }; });
router.get("/debug-sentry", async () => { throw new Error("Test Koa error!"); });

app.use(router.routes());
app.use(router.allowedMethods());
app.listen(3000);

Note: setupKoaErrorHandler has no shouldHandleError option — it captures all errors.

---

Hapi

setupHapiErrorHandler is async — you must await it. Internally registers a Hapi lifecycle extension on onPreResponse.

require("./instrument");
const Sentry = require("@sentry/node");
const Hapi = require("@hapi/hapi");

const init = async () => {
  const server = Hapi.server({ port: 3000, host: "localhost" });

  // ↓ MUST be awaited!
  await Sentry.setupHapiErrorHandler(server);

  server.route({
    method: "GET",
    path: "/debug-sentry",
    handler: () => { throw new Error("Test Hapi error!"); },
  });

  await server.start();
  console.log("Server running on %s", server.info.uri);
};

init();

Caution: Forgetting await silently skips Sentry registration. No error is thrown.

---

Connect

Error handler goes before routes.

require("./instrument");
const connect = require("connect");
const Sentry = require("@sentry/node");

const app = connect();

// ↓ Sentry BEFORE routes
Sentry.setupConnectErrorHandler(app);

app.use("/", (req, res, next) => {
  res.setHeader("Content-Type", "application/json");
  res.end(JSON.stringify({ hello: "world" }));
});

app.use("/debug-sentry", (req, res, next) => {
  throw new Error("Test Connect error!");
});

// Your own error handler (after Sentry)
app.use((err, req, res, next) => {
  res.statusCode = err.status || 500;
  res.end("Internal Server Error");
});

require("http").createServer(app).listen(3000);

---

NestJS

NestJS has a dedicated skill: [`sentry-nestjs-sdk`](../sentry-nestjs-sdk/SKILL.md)

>

NestJS uses a separate package (@sentry/nestjs) with NestJS-native error handling

via SentryGlobalFilter, SentryModule.forRoot(), @SentryExceptionCaptured decorator,

and GraphQL/Microservices support. Load that skill for complete NestJS error monitoring

setup including HttpException filtering, custom filters, and background job isolation.

---

Vanilla Node.js (http Module)

No framework integration needed — rely on the global uncaughtException / unhandledRejection handlers plus manual captureException for caught errors.

require("./instrument");
const http = require("http");
const Sentry = require("@sentry/node");

const server = http.createServer(async (req, res) => {
  try {
    const data = await handleRequest(req);
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify(data));
  } catch (err) {
    Sentry.captureException(err, {
      tags: { path: req.url, method: req.method },
    });
    res.writeHead(500, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ error: "Internal Server Error" }));
  }
});

server.listen(3000);

---

captureException — Full API

function captureException(
  exception: unknown,
  captureContext?: CaptureContext | ((scope: Scope) => Scope)
): string; // returns EventId

type CaptureContext = Scope | Partial<ScopeContext> | ((scope: Scope) => Scope);

interface ScopeContext {
  user?: User;
  level?: "fatal" | "error" | "warning" | "log" | "info" | "debug";
  extra?: Record<string, unknown>;
  tags?: Record<string, Primitive>;
  contexts?: Record<string, Record<string, unknown>>;
  fingerprint?: string[];
}

// Basic
Sentry.captureException(new Error("Something broke"));

// With inline CaptureContext
Sentry.captureException(error, {
  level: "fatal",
  tags: { order_id: orderId, payment_method: "stripe" },
  user: { id: req.user.id, email: req.user.email },
  extra: { requestBody: req.body, retryCount: 3 },
  fingerprint: ["order-processing-failure", orderId],
  contexts: {
    order: { id: orderId, total: 99.99, currency: "USD" },
  },
});

// Scope callback form — most flexible
Sentry.captureException(error, (scope) => {
  scope.setTag("component", "payment");
  scope.setLevel("error");
  scope.setTransactionName("POST /orders");
  return scope; // must return scope
});

// Non-Error values are accepted (but stack traces may be synthetic)
Sentry.captureException("something broke");
Sentry.captureException({ code: "AUTH_FAILED", userId: 42 });

// Capture and use the returned event ID
const eventId = Sentry.captureException(err);
res.status(500).json({ error: "Something went wrong", eventId });

---

captureMessage

function captureMessage(
  message: string,
  captureContext?: CaptureContext | SeverityLevel
): string; // returns EventId

type SeverityLevel = "fatal" | "error" | "warning" | "log" | "info" | "debug";

// Basic
Sentry.captureMessage("Payment gateway timeout");

// With severity level shorthand
Sentry.captureMessage("Disk usage above 90%", "warning");
Sentry.captureMessage("Cache miss rate critical", "fatal");
Sentry.captureMessage("User signed up", "info");

// With full context
Sentry.captureMessage("Rate limit exceeded", {
  level: "warning",
  tags: { service: "api-gateway", region: "us-east-1" },
  user: { id: req.user.id },
  extra: { requestsPerMinute: 1500, limit: 1000 },
  fingerprint: ["rate-limit", req.headers["x-client-id"]],
});

---

Scope Management (v8+ — Hub Removed)

In SDK v8, Hub is removed. Use the three scope types directly.

Priority (current wins): Current > Isolation > Global

// All Sentry.setXXX() top-level methods write to the ISOLATION scope
Sentry.setTag("key", "value");
// identical to:
Sentry.getIsolationScope().setTag("key", "value");

// Global scope — survives the lifetime of the process
Sentry.getGlobalScope().setTag("server_region", "eu-west-1");
Sentry.getGlobalScope().setContext("runtime", {
  name: "node",
  version: process.version,
});

withScope — Temporary Per-Capture Context

Primary tool for adding context to a single capture without contaminating other events.

Sentry.withScope((scope) => {
  scope.setTag("payment_method", "stripe");
  scope.setFingerprint(["stripe-payment-error"]);
  scope.setLevel("error");
  scope.setUser({ id: req.user.id });
  scope.setContext("cart", { items: req.body.items.length });
  scope.addBreadcrumb({ category: "payment", message: "Attempt #3", level: "info" });
  Sentry.captureException(stripeError);
  // All above ONLY applies to this one capture
});

withIsolationScope — Full Isolation (Background Jobs)

Use for background jobs, workers, and queue processors where you need a completely clean scope.

Sentry.withIsolationScope(async (scope) => {
  scope.setUser({ id: job.userId });
  scope.setTag("job_type", job.type);
  scope.setTag("job_id", job.id);
  await processJob(job); // all events inside are fully isolated from other jobs
});

Scope Decision Guide

---

Context Enrichment

setTag / setTags — Indexed, Searchable

Tags are indexed — use them for filtering, grouping, and alerting. Key: max 32 chars, [a-zA-Z0-9_.:−]. Value: max 200 chars.

Sentry.setTag("db_region", "us-east-1");
Sentry.setTag("feature_flag_new_ui", true);
Sentry.setTags({
  service: "checkout",
  version: "2.1.4",
  region: "eu",
});

setContext — Structured, Non-Searchable

Attaches structured data visible in the issue detail view. Not indexed. Normalized to 3 levels deep. The type key is reserved — don't use it.

Sentry.setContext("order", {
  id: orderId,
  total: 99.99,
  currency: "USD",
  coupon: "SAVE20",
});
Sentry.setContext("database", {
  host: "postgres.internal",
  query_duration_ms: 4523,
  active_connections: 19,
});
Sentry.setContext("order", null); // clear it

setUser — User Identity

// On login (writes to isolation scope — safe per-request)
Sentry.setUser({
  id: user.id,
  email: user.email,
  username: user.displayName,
  subscription_tier: "pro", // custom fields accepted
});

// On logout
Sentry.setUser(null);

// Express middleware pattern — set per-request
app.use((req, res, next) => {
  if (req.user) {
    Sentry.setUser({ id: req.user.id, email: req.user.email });
  }
  next();
});

setExtra / setExtras — Arbitrary Data

Non-indexed supplementary data. Prefer setContext for structured objects.

Sentry.setExtra("server_memory_mb", process.memoryUsage().heapUsed / 1024 / 1024);
Sentry.setExtras({
  uptime: process.uptime(),
  node_version: process.version,
});

Tags vs Context vs Extra

---

Breadcrumbs

Automatic Breadcrumbs (Zero Config)

Manual Breadcrumbs

Sentry.addBreadcrumb({
  category: "auth",
  message: `User ${user.email} authenticated`,
  level: "info",
  data: { method: "oauth2", provider: "google" },
});

Sentry.addBreadcrumb({
  type: "http",
  category: "http",
  data: {
    method: "POST",
    url: "https://api.stripe.com/v1/charges",
    status_code: 402,
  },
  level: "warning",
});

Sentry.addBreadcrumb({
  type: "query",
  category: "db.query",
  message: "SELECT * FROM orders WHERE user_id = ?",
  data: { db: "postgres", duration_ms: 42 },
});

Breadcrumb Properties

---

beforeSend and Filtering Hooks

beforeSend — Modify or Drop Error Events

Last chance to modify or drop events. Runs after all event processors. Return null to drop. Only one `beforeSend` is allowed — use addEventProcessor for multiple processors.

Sentry.init({
  beforeSend(event, hint) {
    const err = hint.originalException;

    // Drop in development
    if (process.env.NODE_ENV === "development") return null;

    // Drop specific error types
    if (err instanceof ConnectionResetError) return null;
    if (err?.message?.includes("ECONNRESET")) return null;

    // Scrub PII from user object
    if (event.user) {
      delete event.user.email;
      delete event.user.ip_address;
    }

    // Scrub sensitive keys from request body
    if (event.request?.data) {
      try {
        const body = JSON.parse(event.request.data as string);
        delete body.password;
        delete body.token;
        event.request.data = JSON.stringify(body);
      } catch {}
    }

    // Custom fingerprint from error properties
    if (err instanceof ApiError) {
      event.fingerprint = ["api-error", String(err.statusCode), err.endpoint];
    }

    // Filter noisy breadcrumbs
    if (event.breadcrumbs?.values) {
      event.breadcrumbs.values = event.breadcrumbs.values.filter(
        (bc) => !bc.data?.url?.includes("/health")
      );
    }

    return event;
  },

  // Drop specific transaction/span events
  beforeSendTransaction(event) {
    if (event.transaction === "GET /health") return null;
    if (event.transaction === "GET /ping") return null;
    return event;
  },
});

beforeBreadcrumb — Filter or Mutate Breadcrumbs

Sentry.init({
  beforeBreadcrumb(breadcrumb, hint) {
    // Drop health-check HTTP requests
    if (
      breadcrumb.type === "http" &&
      breadcrumb.data?.url?.includes("/health")
    ) {
      return null;
    }

    // Redact auth tokens from URLs
    if (breadcrumb.type === "http" && breadcrumb.data?.url) {
      try {
        const url = new URL(breadcrumb.data.url);
        url.searchParams.delete("token");
        url.searchParams.delete("api_key");
        breadcrumb.data.url = url.toString();
      } catch {}
    }

    return breadcrumb;
  },
  maxBreadcrumbs: 50, // default: 100
});

ignoreErrors — Pattern-Based Filtering

Sentry.init({
  ignoreErrors: [
    "Non-Error exception captured",
    /^ECONNRESET/,
    /^ETIMEDOUT/,
    /^socket hang up/,
  ],
  ignoreTransactions: [
    "GET /health",
    "GET /ping",
    "GET /metrics",
    /^GET \/internal\//,
  ],
});

---

Fingerprinting and Custom Grouping

All events have a fingerprint array. Events with the same fingerprint group into the same Sentry issue.

Per-Capture Fingerprinting

Sentry.captureException(error, {
  fingerprint: ["payment-declined", req.body.payment_method],
});

withScope Fingerprinting

Sentry.withScope((scope) => {
  scope.setFingerprint([req.method, req.path, String(err.statusCode)]);
  Sentry.captureException(err);
});

beforeSend Fingerprinting (Global Rules)

Sentry.init({
  beforeSend(event, hint) {
    const err = hint.originalException;

    // All DB connection errors → one group
    if (err instanceof DatabaseConnectionError) {
      event.fingerprint = ["database-connection-error"];
    }

    // Group ApiErrors by status + endpoint
    if (err instanceof ApiError) {
      event.fingerprint = ["api-error", String(err.statusCode), err.endpoint];
    }

    // Extend Sentry's default algorithm (keep stack-trace hash + add dimension)
    if (err?.code) {
      event.fingerprint = ["{{ default }}", err.code];
    }

    return event;
  },
});

Template Variables

---

Event Processors

Unlike beforeSend (one allowed), multiple event processors can be registered. Order is not guaranteed. beforeSend always runs last.

// Runs on every event — enrich with deploy metadata
Sentry.addEventProcessor((event, hint) => {
  event.tags = {
    ...event.tags,
    git_sha: process.env.GIT_SHA ?? "unknown",
    deployed_by: process.env.DEPLOY_USER ?? "unknown",
  };
  return event;
});

// Drop events with a custom ignore flag
Sentry.addEventProcessor((event, hint) => {
  if ((hint.originalException as any)?.ignore_in_sentry === true) return null;
  return event;
});

// Scope-level processor (only inside withScope callback)
Sentry.withScope((scope) => {
  scope.addEventProcessor((event) => {
    event.tags = { ...event.tags, batch_job: "true" };
    return event;
  });
  Sentry.captureException(new Error("job failed"));
});

`addEventProcessor` vs `beforeSend`:

---

requestDataIntegration — Per-Request Data

Auto-enabled. Attaches HTTP request data to all events during a request. Each framework auto-forks an isolation scope per request via OpenTelemetry AsyncLocalStorage — concurrent requests stay separate.

Sentry.init({
  sendDefaultPii: true,
  integrations: [
    Sentry.requestDataIntegration({
      include: {
        cookies: true,
        data: true,         // request body
        headers: true,
        ip: true,
        query_string: true,
        url: true,
        user: { id: true, username: true, email: false },
      },
    }),
  ],
});

---

Error Chains

linkedErrorsIntegration is auto-enabled and follows the standard Error.cause chain.

// Standard Error.cause — captured automatically
try {
  await connectToDatabase();
} catch (dbError) {
  throw new Error("Failed to process order", { cause: dbError });
  // Sentry captures BOTH errors as a chain
}

// Configure depth (default: 5)
Sentry.init({
  integrations: [
    Sentry.linkedErrorsIntegration({ key: "cause", limit: 5 }),
  ],
});

extraErrorDataIntegration — Custom Error Properties

Captures non-standard properties on Error subclasses:

Sentry.init({
  integrations: [Sentry.extraErrorDataIntegration({ depth: 3 })],
});

class HttpError extends Error {
  constructor(message, response) {
    super(message);
    this.statusCode = response.status;    // captured in extras
    this.responseBody = response.body;    // captured in extras
    this.endpoint = response.url;         // captured in extras
  }
}

---

Lifecycle: Flush Before Shutdown

@sentry/node batches events and sends asynchronously. Always flush before process exit to avoid losing the last events.

// Graceful shutdown — HTTP server
process.on("SIGTERM", async () => {
  server.close(async () => {
    await Sentry.flush(2000); // wait up to 2s for queue to drain
    process.exit(0);
  });
});

// Serverless (Lambda, Cloud Functions) — close disables SDK after flush
export const handler = async (event) => {
  try {
    return await processEvent(event);
  } catch (err) {
    Sentry.captureException(err);
    await Sentry.close(2000); // flush + disable before function freezes
    throw err;
  }
};

---

Sentry.init() — Error-Relevant Options

Sentry.init({
  // Identity
  dsn?: string;                    // also: SENTRY_DSN env var
  release?: string;                // "my-app@1.2.3+abc123"
  environment?: string;            // default: "production"
  serverName?: string;             // hostname
  enabled?: boolean;               // default: true

  // Sampling
  sampleRate?: number;             // 0.0–1.0 error event sample rate
  tracesSampleRate?: number;       // 0.0–1.0 transaction sample rate

  // Data limits
  maxBreadcrumbs?: number;         // default: 100
  maxValueLength?: number;         // truncate long strings
  normalizeDepth?: number;         // default: 3

  // Privacy
  sendDefaultPii?: boolean;        // default: false — enables body/cookies/IP

  // Filtering
  ignoreErrors?: Array<string | RegExp>;
  ignoreTransactions?: Array<string | RegExp>;

  // Hooks
  beforeSend?: (event: Event, hint: EventHint) => Event | null;
  beforeSendTransaction?: (event: Event, hint: EventHint) => Event | null;
  beforeBreadcrumb?: (breadcrumb: Breadcrumb, hint?: BreadcrumbHint) => Breadcrumb | null;

  // Node-specific
  enableLogs?: boolean;             // default: false — Sentry.logger.*
  attachStacktrace?: boolean;       // add stack traces to captureMessage
  includeLocalVariables?: boolean;  // include local vars in stack frames
  onFatalError?: (error: Error) => void;
  shutdownTimeout?: number;         // default: 2000ms
});

---

Bun

@sentry/bun is a thin wrapper over @sentry/node. The API is identical — use --preload instead of require("./instrument") first.

// instrument.ts
import * as Sentry from "@sentry/bun";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  tracesSampleRate: 1.0,
  sendDefaultPii: true,
});

bun --preload ./instrument.ts server.ts

For Bun.serve():

import * as Sentry from "@sentry/bun";

const server = Bun.serve({
  port: 3000,
  fetch(request) {
    return new Response("Hello from Bun!");
  },
  error(error) {
    Sentry.captureException(error); // manual — no setupErrorHandler for Bun.serve
    return new Response("Internal Server Error", { status: 500 });
  },
});

Profiling: @sentry/profiling-node uses a native addon — incompatible with Bun's runtime. Omit nodeProfilingIntegration() in Bun apps.

---

Deno

// instrument.ts
import * as Sentry from "npm:@sentry/deno";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  tracesSampleRate: 1.0,
});

// server.ts
import "../instrument.ts";
import * as Sentry from "npm:@sentry/deno";

Deno.serve({ port: 3000 }, async (request) => {
  try {
    return new Response("Hello from Deno!");
  } catch (error) {
    Sentry.captureException(error);
    return new Response("Internal Server Error", { status: 500 });
  }
});

Requirements: Deno 2+. Run with --allow-net --allow-env --allow-read. No setupExpressErrorHandler equivalent — use try/catch + captureException.

---

Quick Reference

// Init
Sentry.init({ dsn: "...", tracesSampleRate: 1.0 });

// Capture
Sentry.captureException(new Error("oops"));
Sentry.captureException(err, { tags: { source: "api" }, level: "fatal" });
Sentry.captureMessage("Something happened", "warning");

// Context (→ isolation scope, auto-forked per request)
Sentry.setUser({ id: 1, email: "user@example.com" });
Sentry.setTag("region", "us-east");
Sentry.setTags({ service: "checkout", version: "2.0" });
Sentry.setContext("cart", { items: 3, total: 49.99 });
Sentry.addBreadcrumb({ category: "auth", message: "login", level: "info" });

// Scoped capture (temporary context, one event only)
Sentry.withScope((scope) => {
  scope.setTag("temp_tag", "only-this-event");
  scope.setFingerprint(["my-custom-group"]);
  scope.setLevel("warning");
  Sentry.captureException(err);
});

// Background job isolation
await Sentry.withIsolationScope(async (scope) => {
  scope.setUser({ id: job.userId });
  await processJob(job);
});

// Global (all events, process lifetime)
Sentry.getGlobalScope().setTag("app", "my-api");

// Framework error handlers — placement matters!
Sentry.setupExpressErrorHandler(app);          // Express: AFTER routes
Sentry.setupFastifyErrorHandler(app);          // Fastify: BEFORE routes
Sentry.setupKoaErrorHandler(app);              // Koa: FIRST middleware
await Sentry.setupHapiErrorHandler(server);    // Hapi: BEFORE routes, MUST await
Sentry.setupConnectErrorHandler(app);          // Connect: BEFORE routes

// Shutdown
await Sentry.flush(2000);

---

Troubleshooting

Logging — Sentry Node.js SDK

Minimum SDK: @sentry/node ≥9.41.0 (stable GA)

First experimental: ≥9.10.0 (via _experiments.enableLogs)

Console multi-arg parsing: ≥10.13.0

Consola reporter: ≥10.12.0

Scope attributes on logs: ≥10.32.0

Status: ✅ Generally Available

---

Overview

Sentry Logs are high-cardinality structured log entries that link directly to traces and errors. They let you answer why something broke, not just what broke.

Key characteristics:

• Sent as structured data — each attribute is individually searchable in Sentry UI
• Automatically linked to the active trace (if tracing is enabled)
• Buffered and batched (max 100 per buffer) — no per-log network overhead
• NOT a replacement for a logging library; designed to complement one

---

Initialization

enableLogs: true is required. Logging is disabled by default.

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  enableLogs: true,                   // REQUIRED — default: false

  beforeSendLog: (log) => {           // optional filter/transform
    if (log.level === "debug") return null;  // null = drop this log
    return log;
  },
});

---

Logger API

All six methods live at Sentry.logger.*:

Sentry.logger.trace(message, attributes?, options?)
Sentry.logger.debug(message, attributes?, options?)
Sentry.logger.info(message, attributes?, options?)
Sentry.logger.warn(message, attributes?, options?)
Sentry.logger.error(message, attributes?, options?)
Sentry.logger.fatal(message, attributes?, options?)

Full TypeScript signature (same shape for all six methods):

function info(
  message: ParameterizedString,          // string or fmt`` tagged template
  attributes?: Record<string, unknown>,  // string | number | boolean values
  options?: { scope?: Scope },           // optional scope override
): void;

---

Basic Usage

Sentry.logger.trace("Entering function", { fn: "processOrder" });
Sentry.logger.debug("Cache lookup", { key: "user:123", hit: false });
Sentry.logger.info("Order created", { orderId: "order_456", total: 99.99 });
Sentry.logger.warn("Rate limit approaching", { current: 95, max: 100 });
Sentry.logger.error("Payment failed", { reason: "card_declined", userId: 42 });
Sentry.logger.fatal("Database unavailable", { host: "primary-db", port: 5432 });

---

Parameterized Messages — Sentry.logger.fmt

Use the fmt tagged template literal to create parameterized messages. Interpolated values are extracted as individually searchable attributes in Sentry.

const userId = "user_123";
const productName = "Widget Pro";

Sentry.logger.info(
  Sentry.logger.fmt`User ${userId} purchased ${productName}`,
);

// Stored in Sentry as:
// sentry.message.template  → "User '%s' purchased '%s'"
// sentry.message.parameter.0 → "user_123"
// sentry.message.parameter.1 → "Widget Pro"

You can combine fmt with additional attributes:

Sentry.logger.info(
  Sentry.logger.fmt`Order ${orderId} placed by ${userId}`,
  { total: 149.99, itemCount: 3, region: "us-west-2" },
);

fmt is an alias for Sentry.parameterize() internally. The returned string carries hidden __sentry_template_string__ and __sentry_template_values__ properties used by the SDK for serialization.

---

Structured Attributes

The second argument is a plain object. Values must be string, number, or boolean.

Sentry.logger.info("API request completed", {
  userId: user.id,
  userTier: user.plan,          // "free" | "pro" | "enterprise"
  endpoint: "/api/orders",
  method: "POST",
  statusCode: 200,
  durationMs: 234,
  orderValue: 149.99,
  isBeta: true,
  retryCount: 0,
});

Attributes become filterable columns in the Sentry Logs view.

---

Scope-Based Attributes (SDK ≥10.32.0)

Set attributes on a scope once and they are automatically attached to every log emitted within that scope.

// Global scope — applies to all logs for the app's lifetime
Sentry.getGlobalScope().setAttributes({
  service: "checkout-service",
  version: "2.1.0",
  region: "us-west-2",
});

// Isolation scope — unique per HTTP request (auto-created by HTTP integrations)
Sentry.getIsolationScope().setAttributes({
  org_id: user.orgId,
  user_tier: user.tier,
  request_id: req.id,
});

// Current scope — single operation block
Sentry.withScope((scope) => {
  scope.setAttribute("operation", "payment-processing");
  scope.setAttribute("payment_method", "stripe");

  Sentry.logger.info("Processing payment", { amount: 99.99 });
  // → includes all scope attributes + the explicit { amount }
});

---

Auto-Attached Attributes

The SDK automatically attaches these to every log:

---

Console Integration

Capture console.* calls as Sentry logs using the built-in integration (SDK ≥9.41.0):

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  enableLogs: true,
  integrations: [
    Sentry.consoleLoggingIntegration({
      levels: ["log", "warn", "error"],
      // Default levels: ['debug','info','warn','error','log','trace','assert']
    }),
  ],
});

// These now send to Sentry Logs automatically:
console.log("User action:", "checkout");   // → severity: info
console.warn("Memory pressure");           // → severity: warn
console.error("Unhandled rejection");      // → severity: error

Multi-argument parsing (args become message.parameter.N attributes) requires SDK ≥10.13.0.

---

Consola Integration (SDK ≥10.12.0)

import { createConsola } from "consola";
import * as Sentry from "@sentry/node";

const logger = createConsola();
logger.addReporter(Sentry.createConsolaReporter());

logger.info("This goes to Sentry Logs");
logger.error("This too");

---

beforeSendLog Hook

Filter or transform logs before they are sent. Return null to drop:

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  enableLogs: true,
  beforeSendLog: (log) => {
    // Drop debug logs in production
    if (process.env.NODE_ENV === "production" && log.level === "debug") {
      return null;
    }

    // Scrub sensitive fields
    if (log.attributes?.credit_card) {
      log.attributes.credit_card = "[REDACTED]";
    }

    // Add computed attributes
    log.attributes = {
      ...log.attributes,
      processed_at: Date.now(),
    };

    return log;
  },
});

The log object shape: { level, message, attributes, severityNumber }.

---

Third-Party Logger Bridges

Sentry does not provide official first-party transports for Winston, Pino, Bunyan, or Morgan. Use the patterns below to forward logs to Sentry.logger.*.

Winston:

import winston from "winston";
import * as Sentry from "@sentry/node";

const levelMap: Record<string, keyof typeof Sentry.logger> = {
  silly: "trace", verbose: "debug", debug: "debug",
  http: "info", info: "info", warn: "warn", error: "error",
};

const sentryTransport = new winston.transports.Stream({
  stream: {
    write: (message: string) => {
      const parsed = JSON.parse(message);
      const fn = levelMap[parsed.level] ?? "info";
      (Sentry.logger[fn] as Function)(parsed.message, parsed.meta ?? {});
    },
  },
});

const logger = winston.createLogger({
  format: winston.format.json(),
  transports: [new winston.transports.Console(), sentryTransport],
});

Pino:

import pino from "pino";
import * as Sentry from "@sentry/node";

const PINO_TO_SENTRY: Record<number, keyof typeof Sentry.logger> = {
  10: "trace", 20: "debug", 30: "info",
  40: "warn", 50: "error", 60: "fatal",
};

const dest = pino.destination({
  write(chunk: string) {
    const log = JSON.parse(chunk);
    const fn = PINO_TO_SENTRY[log.level] ?? "info";
    const { msg, level, time, pid, hostname, ...attrs } = log;
    (Sentry.logger[fn] as Function)(msg, attrs);
  },
});

const logger = pino({ level: "trace" }, dest);

---

Trace Linking

Logs emitted during an active span automatically include sentry.trace.parent_span_id, linking them to the active trace. From a log in Sentry you can navigate to its parent trace; from a trace you can see all logs emitted during that request.

---

Log Buffering and Flushing

Logs are buffered in memory (max 100 per buffer: MAX_LOG_BUFFER_SIZE = 100). The buffer flushes automatically when full or on client.close().

For serverless or short-lived processes, flush explicitly before exit:

await Sentry.flush(2000);  // flush with 2s timeout
await Sentry.close(2000);  // flush + close all transports

---

Troubleshooting

Metrics — Sentry Node.js SDK

Minimum SDK: @sentry/node ≥10.25.0 (stable Sentry.metrics.* API)

enableMetrics top-level option: ≥10.24.0 (default: true)

beforeSendMetric hook: ≥10.24.0

Scope attributes on metrics: ≥10.33.0

---

Overview

Sentry Metrics let you track counters, current values, and value distributions. They appear in Sentry alongside related errors and can be correlated with traces.

Key characteristics:

• Metrics are enabled by default — no configuration required for basic use
• Buffered in memory (max 1000 entries) and sent periodically
• High-cardinality attributes degrade backend performance — keep attribute cardinality low
• Use Sentry.logger.* (not metrics) when you need per-user or per-request detail

---

Initialization

Metrics are on by default. Opt out if needed:

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  // Metrics are enabled by default — no config needed

  // To disable entirely:
  // enableMetrics: false,

  beforeSendMetric: (metric) => {   // optional filter/transform
    if (metric.name === "debug_metric") return null;
    return metric;
  },
});

---

Metrics API

Three methods. No increment() or set() — those do not exist in v10:

Sentry.metrics.count(name, value?, options?)
Sentry.metrics.gauge(name, value, options?)
Sentry.metrics.distribution(name, value, options?)

Full TypeScript signatures:

interface MetricOptions {
  unit?: string;                           // see unit table below
  attributes?: Record<string, unknown>;    // filterable dimensions
  scope?: Scope;                           // optional scope override
}

function count(name: string, value?: number, options?: MetricOptions): void;
       // value defaults to 1

function gauge(name: string, value: number, options?: MetricOptions): void;

function distribution(name: string, value: number, options?: MetricOptions): void;

---

Metric Types

// count — how many times something happened
Sentry.metrics.count("user.signups", 1);
Sentry.metrics.count("api.errors", 1, { attributes: { endpoint: "/checkout" } });

// gauge — what the current state is
Sentry.metrics.gauge("queue.depth", 42);
Sentry.metrics.gauge("memory.usage", 512, { unit: "megabyte" });

// distribution — spread of a measured value
Sentry.metrics.distribution("api.latency", 187.5, { unit: "millisecond" });
Sentry.metrics.distribution("payload.size", 1024, { unit: "byte" });

---

Units

Pass a unit string in MetricOptions. Used for display formatting in Sentry.

Sentry.metrics.distribution("api.latency", 187.5, { unit: "millisecond" });
Sentry.metrics.distribution("job.duration", 3.2,   { unit: "second" });
Sentry.metrics.gauge("memory.usage", 512,          { unit: "megabyte" });
Sentry.metrics.gauge("cache.hit_rate", 0.87,       { unit: "ratio" });
Sentry.metrics.gauge("disk.usage_pct", 72.4,       { unit: "percent" });
Sentry.metrics.count("user.logins");               // omit unit for plain counts

---

Attributes (Tags)

Use attributes in MetricOptions to add filterable/groupable dimensions.

Size limit: 2 KB per metric envelope. Metrics exceeding this are dropped.

Sentry.metrics.count("api.requests", 1, {
  attributes: {
    endpoint: "/api/orders",
    method: "POST",
    status_code: 200,
    user_tier: "pro",
    region: "us-west-2",
    version: "v2",
  },
});

Sentry.metrics.distribution("db.query_time", 45.3, {
  unit: "millisecond",
  attributes: {
    table: "orders",
    operation: "SELECT",
    index_used: true,
    rows_scanned: 1240,
  },
});

---

Cardinality

Keep attribute values bounded. High-cardinality attributes (per-user IDs, request UUIDs) cause performance issues in Sentry's metrics backend.

// ❌ HIGH CARDINALITY — avoid as metric attributes
Sentry.metrics.count("page.view", 1, {
  attributes: { user_id: "uuid-abc-123" },   // millions of unique values
});

// ✅ LOW CARDINALITY — bounded enums and sets
Sentry.metrics.count("page.view", 1, {
  attributes: {
    page: "/dashboard",
    user_tier: "pro",        // bounded enum
    ab_variant: "control",   // bounded enum
    region: "us-east-1",     // bounded set
  },
});

Use Sentry.logger.* for per-user or per-request data — logs handle high cardinality gracefully.

---

Scope-Based Attributes (SDK ≥10.33.0)

Set attributes on a scope and they auto-attach to all metrics emitted within it:

// Global scope — applies to all metrics app-wide
Sentry.getGlobalScope().setAttributes({
  service: "payments",
  deploy_env: "production",
});

// Per-request scope
Sentry.withScope((scope) => {
  scope.setAttribute("step", "checkout");
  scope.setAttribute("user_tier", "enterprise");

  // Both metrics inherit the scope attributes above
  Sentry.metrics.count("checkout.attempts", 1);
  Sentry.metrics.gauge("cart.value", 249.99);
});

---

Auto-Attached Default Attributes

---

beforeSendMetric Hook

Filter or modify metrics before transmission. Return null to drop:

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  beforeSendMetric: (metric) => {
    // metric: { name, value, type, unit?, attributes? }

    // Drop internal debug metrics
    if (metric.name.startsWith("_internal.")) {
      return null;
    }

    // Normalize metric names
    metric.name = metric.name.toLowerCase().replace(/[^a-z0-9_.]/g, "_");

    // Add global context
    metric.attributes = {
      ...metric.attributes,
      host: process.env.HOSTNAME,
      deploy_id: process.env.DEPLOY_ID,
    };

    return metric;
  },
});

---

Flushing

Metrics are buffered (max MAX_METRIC_BUFFER_SIZE = 1000) and flushed periodically. For serverless or short-lived scripts, flush explicitly:

await Sentry.flush(2000);  // flush + 2s timeout
await Sentry.close(2000);  // flush + close all transports

---

Troubleshooting

Profiling — Sentry Node.js SDK

Node.js profiling: @sentry/profiling-node — must match your @sentry/node version exactly

Bun and Deno are NOT supported. The profiler is a native C++ addon (node-gyp) that only runs in Node.js.

---

Overview

Profiling captures V8 CPU call stacks at ~100 samples/second alongside your traces. Profiles attach to spans, giving you flame graphs to identify hot paths directly from a slow trace.

Profiling is Node.js only:

---

How Profiling Relates to Tracing

Profiles attach to spans — they require tracing to be enabled:

1. tracesSampleRate / tracesSampler decides whether a request is traced at all 2. profileSessionSampleRate decides whether the session opts into profiling 3. A profile is only collected when both sampling decisions are "yes"

tracesSampleRate: 0.1   +  profileSessionSampleRate: 0.5
→ ~5% of requests will have both a trace AND a profile attached

In trace lifecycle mode, you can drill from a slow span in the Performance UI directly into a flame graph:

Trace: "POST /api/checkout" (850ms)
  ├── "validateCart" (45ms)   → [Profile attached] → shows DB driver hot paths
  ├── "processPayment" (620ms)
  └── "updateInventory" (185ms) → [Profile attached] → shows ORM overhead

---

Installation

npm install @sentry/profiling-node --save

⚠️ Version pinning is required. @sentry/profiling-node must exactly match your @sentry/node version. Mismatched versions cause silent failures or startup crashes.

# Both must be the same version
npm install @sentry/node@latest @sentry/profiling-node@latest

---

SDK Configuration

Trace Mode (Recommended)

Profiles auto-attach to all sampled spans with no additional code:

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,

  integrations: [
    nodeProfilingIntegration(),
  ],

  tracesSampleRate: 1.0,

  // Session-level sampling: decision made once at process startup
  profileSessionSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,

  // "trace" = profiles auto-attach to every sampled span
  profileLifecycle: "trace",
});

Manual Mode

Start and stop profiling around specific code paths:

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  integrations: [nodeProfilingIntegration()],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 1.0,
  profileLifecycle: "manual",
});

// Explicit start/stop around critical code:
Sentry.profiler.startProfiler();
await heavyComputation();
Sentry.profiler.stopProfiler();

---

Continuous Profiling

For long-running processes, batch jobs, or background workers that don't map cleanly to request spans, use the profiler API directly:

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  integrations: [nodeProfilingIntegration()],
});

// Start profiling at process startup
Sentry.profiler.startProfiler();

// Profile is chunked automatically into ~60-second intervals and uploaded
// All spans created during this window have profile data attached

// Stop when done (e.g. graceful shutdown)
process.on("SIGTERM", () => {
  Sentry.profiler.stopProfiler();
  process.exit(0);
});

Profile Chunk Architecture

The V2 profiler divides data into 60-second chunks that upload automatically:

Process lifetime:
┌─── 60 seconds ───┬─── 60 seconds ───┬─── 60 seconds ───┐
│   Chunk 1        │   Chunk 2        │   Chunk 3        │
│   Spans: [...]   │   Spans: [...]   │   Spans: [...]   │
│   Sent at 60s    │   Sent at 120s   │   Sent at 180s   │
└──────────────────┴──────────────────┴──────────────────┘

This means there's no 30-second max like in the legacy V1 API — the profiler runs as long as your process does.

---

Profiler API Reference

Sentry.profiler.startProfiler()

Starts the V8 CpuProfiler. Call this once at process startup or before the code you want to profile.

Sentry.profiler.startProfiler();

• No-ops gracefully if already running
• Takes effect immediately
• Overhead is low; safe to call at startup in production

Sentry.profiler.stopProfiler()

Stops the profiler and flushes remaining profile data to Sentry.

Sentry.profiler.stopProfiler();

• Flushes the current in-progress chunk
• Call on graceful shutdown to avoid losing the last partial chunk

Manual Start/Stop Pattern

// Profile a specific batch job, not the entire process
async function runNightlyBatch() {
  Sentry.profiler.startProfiler();
  try {
    await Sentry.startSpan({ op: "batch", name: "nightly-sync" }, async () => {
      await syncUsers();
      await syncOrders();
      await syncInventory();
    });
  } finally {
    Sentry.profiler.stopProfiler();
  }
}

---

Configuration Reference

profileSessionSampleRate Semantics

The profiling sampling decision is made once per process startup — not per request.

A "profiling session" either opts in or opts out for its entire lifetime. Within a profiling session, every traced span gets a profile attached (in trace mode).

// 10% of Node.js processes will profile all their requests
profileSessionSampleRate: 0.1

profileLifecycle Modes

---

Supported Platforms

Precompiled native binaries are available for:

❌ FreeBSD, 32-bit systems, Bun, and Deno are not supported.

The native addon requires Node.js — it cannot run in other runtimes.

Alpine Linux / Docker

The musl libc variant is included automatically. If you see missing binary errors on Alpine:

# Ensure you're installing native dependencies
RUN npm install --include=optional

Or rebuild from source:

RUN apk add --no-cache python3 make g++ && npm rebuild @sentry/profiling-node

---

Environment Variables

# Override profiler binary path (for custom builds or non-standard environments)
SENTRY_PROFILER_BINARY_PATH=/custom/path/sentry_cpu_profiler.node

# Override binary directory
SENTRY_PROFILER_BINARY_DIR=/path/to/dir

# Profiler logging mode:
# "eager" (default) — faster startProfiler calls, slightly more CPU overhead
# "lazy"            — lower CPU overhead, slightly slower startProfiler
SENTRY_PROFILER_LOGGING_MODE=lazy node server.js

---

Production Recommendations

Sentry.init({
  integrations: [nodeProfilingIntegration()],
  tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
  profileSessionSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
  profileLifecycle: "trace",
});

Performance impact notes:

• Sampling rate (~100Hz): The V8 CpuProfiler adds CPU overhead. Test with realistic load before deploying profileSessionSampleRate: 1.0 to high-traffic production.
• Memory: Each 60-second chunk uses ~10–20 MB of buffer. Capped at 50 chunks (~100 MB max).
• Network: One profiling upload per 60-second window per process.

"For high-throughput environments, we recommend testing prior to deployment to ensure that your service's performance characteristics maintain expectations." — Sentry docs

For high-traffic servers, start conservative:

// Start at 1–5% and increase after measuring overhead
profileSessionSampleRate: 0.01

---

Complete Setup Example

// instrument.ts (loaded before app code)
import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";

Sentry.init({
  dsn: process.env.SENTRY_DSN,

  integrations: [
    nodeProfilingIntegration(),
  ],

  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  profileSessionSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  profileLifecycle: "trace",
});

// app.ts
import "./instrument"; // Must be first import
import express from "express";
import * as Sentry from "@sentry/node";

const app = express();

app.get("/api/users", async (req, res) => {
  // Automatically traced + profiled (in profiling sessions)
  const users = await db.query("SELECT * FROM users");
  res.json(users);
});

Sentry.setupExpressErrorHandler(app);
app.listen(3000);

---

Troubleshooting