sentry-nestjs-sdk

All Skills > SDK Setup > NestJS SDK

Sentry NestJS SDK

Opinionated wizard that scans your NestJS project and guides you through complete Sentry setup.

Invoke This Skill When

• User asks to "add Sentry to NestJS" or "setup Sentry" in a NestJS app
• User wants error monitoring, tracing, profiling, logging, metrics, or crons in NestJS
• User mentions @sentry/nestjs or Sentry + NestJS
• User wants to monitor NestJS controllers, services, guards, microservices, or background jobs

Note: SDK versions and APIs below reflect @sentry/nestjs 10.x (NestJS 8–11 supported). Always verify against docs.sentry.io/platforms/node/guides/nestjs/ before implementing.

Phase 1: Detect

Run these commands to understand the project before making recommendations:

# Confirm NestJS project
grep -E '"@nestjs/core"' package.json 2>/dev/null
 
# Check NestJS version
node

What to note:

• Is @sentry/nestjs already installed? If yes, check if instrument.ts exists and Sentry.init() is called — may just need feature config.
• Sentry DI wrapper detected? → The project wraps Sentry behind a DI token (e.g. SENTRY_PROXY_TOKEN) for testability. Use the injected proxy for all runtime Sentry calls (startSpan, captureException, withIsolationScope) instead of importing @sentry/nestjs directly in controllers, services, and processors. Only instrument.ts should import @sentry/nestjs directly.
• Config class detected? → The project uses a typed config class for Sentry.init() options (e.g. loaded from YAML or @nestjs/config). Any new SDK options must be added to the config type — do not hardcode values that should be configurable per environment.
• SentryModule.forRoot() already registered? → If it's in a shared module (e.g. a Sentry proxy module), do not add it again in AppModule — this causes duplicate interceptor registration.
• Express (default) or Fastify adapter? Express is fully supported; Fastify works but has known edge cases.
• GraphQL detected? → SentryGlobalFilter handles it natively.
• Microservices detected? → Recommend RPC exception filter.
• Task queues / @nestjs/schedule? → Recommend crons.
• AI libraries? → Auto-instrumented, zero config.
• Prisma? → Requires manual prismaIntegration().
• Companion frontend? → Triggers Phase 4 cross-link.

Phase 2: Recommend

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

Always recommended (core coverage):

• ✅ Error Monitoring — captures unhandled exceptions across HTTP, GraphQL, RPC, and WebSocket contexts
• ✅ Tracing — auto-instruments middleware, guards, pipes, interceptors, filters, and route handlers

Recommend when detected:

• ✅ Profiling — production apps where CPU performance matters (@sentry/profiling-node)
• ✅ Logging — structured Sentry Logs + optional console capture
• ✅ Crons — @nestjs/schedule, Bull, or BullMQ detected
• ✅ Metrics — business KPIs or SLO tracking
• ✅ AI Monitoring — OpenAI/Anthropic/LangChain/etc. detected (auto-instrumented, zero config)

Recommendation matrix:

Propose: "I recommend Error Monitoring + Tracing + Logging. Want Profiling, Crons, or AI Monitoring too?"

Phase 3: Guide

Install

⚠️ Do NOT install @sentry/node alongside @sentry/nestjs — @sentry/nestjs re-exports everything from @sentry/node. Installing both causes duplicate registration.

Three-File Setup (Required)

NestJS requires a specific three-file initialization pattern because the Sentry SDK must patch Node.js modules (via OpenTelemetry) before NestJS loads them.

Before creating new files, check Phase 1 results:

• If instrument.ts already exists → modify it, don't create a new one.
• If a config class drives Sentry.init() → read options from the config instead of hardcoding env vars.
• If a Sentry DI wrapper exists → use it for runtime calls instead of importing @sentry/nestjs directly in services/controllers.

Step 1: Create src/instrument.ts

Config-driven Sentry.init(): If Phase 1 found a typed config class (e.g. SentryConfig), read options from it instead of using raw process.env. This is common in NestJS apps that use @nestjs/config or custom config loaders:

When adding new SDK options (e.g. dataCollection, profileSessionSampleRate), add them to the config type so they can be configured per environment.

Step 2: Import instrument.ts FIRST in src/main.ts

Why first? OpenTelemetry must monkey-patch http, express, database drivers, and other modules before they load. Any module that loads before instrument.ts will not be auto-instrumented.

Step 3: Register SentryModule and SentryGlobalFilter in src/app.module.ts

What each piece does:

• SentryModule.forRoot() — registers SentryTracingInterceptor as a global APP_INTERCEPTOR, enabling HTTP transaction naming
• SentryGlobalFilter — extends BaseExceptionFilter; captures exceptions across HTTP, GraphQL (rethrows HttpException without reporting), and RPC contexts

⚠️ Do NOT register SentryModule.forRoot() twice. If Phase 1 found it already imported in a shared library module (e.g. a SentryProxyModule or AnalyticsModule), do not add it again in AppModule. Duplicate registration causes every span to be intercepted twice, bloating trace data.

⚠️ Two entrypoints, different imports:

• @sentry/nestjs → SDK init, capture APIs, decorators (SentryTraced, SentryCron, SentryExceptionCaptured)
• @sentry/nestjs/setup → NestJS DI constructs (SentryModule, SentryGlobalFilter)

Never import SentryModule from @sentry/nestjs (main entrypoint) — it loads @nestjs/common before OpenTelemetry patches it, breaking auto-instrumentation.

ESM Setup (Node ≥ 18.19.0)

For ESM applications, use --import instead of a file import:

Or via environment:

Exception Filter Options

Choose the approach that fits your existing architecture:

Option A: No existing global filter — use SentryGlobalFilter (recommended)

Already covered in Step 3 above. This is the simplest option.

Option B: Existing custom global filter — add @SentryExceptionCaptured() decorator

Option C: Specific exception type — manual capture

Option D: Microservice RPC exceptions

Decorators

@SentryTraced(op?) — Instrument any method

@SentryCron(slug, config?) — Monitor scheduled jobs

Background Job Scope Isolation

Background jobs share the default isolation scope — wrap with Sentry.withIsolationScope() to prevent cross-contamination:

Apply withIsolationScope to: @Cron(), @Interval(), @OnEvent(), @Processor(), and any code outside the request lifecycle.

Working with Sentry DI Wrappers

Some NestJS projects wrap Sentry behind a dependency injection token (e.g. SENTRY_PROXY_TOKEN) for testability and decoupling. If Phase 1 detected this pattern, use the injected service for all runtime Sentry calls — do not import @sentry/nestjs directly in controllers, services, or processors.

Where direct @sentry/nestjs import is still correct:

• instrument.ts — always uses import * as Sentry from "@sentry/nestjs" for Sentry.init()
• Standalone scripts and exception filters that run outside the DI container

Verification

Add a test endpoint to confirm events reach Sentry:

Hit GET /debug-sentry and check the Sentry Issues dashboard within seconds.

For Each Agreed Feature

Walk through features one at a time. Load the reference, follow its steps, verify before moving on:

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

Configuration Reference

Key Sentry.init() Options

dataCollection defaults:

• httpHeaders: { request: true, response: true }
• httpBodies: ["incomingRequest", "outgoingRequest", "incomingResponse", "outgoingResponse"]
• userInfo: true
• genAI: { inputs: true, outputs: true }

Environment Variables

Auto-Enabled Integrations

These integrations activate automatically when their packages are detected — no integrations: [...] needed:

Integrations Requiring Manual Setup

Verification

Test that Sentry is receiving events:

Or send a test message without crashing:

If nothing appears:

1. Set debug: true in Sentry.init() — prints SDK internals to stdout
2. Verify SENTRY_DSN env var is set in the running process
3. Check that import "./instrument" is the first line in main.ts
4. Confirm SentryModule.forRoot() is imported in AppModule
5. Check DSN format: https://<key>@o<org>.ingest.sentry.io/<project>

Phase 4: Cross-Link

After completing NestJS setup, check for a companion frontend missing Sentry:

If a frontend exists without Sentry, suggest the matching skill:

Troubleshooting

Version Requirements