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 -e "console.log(require('./node_modules/@nestjs/core/package.json').version)" 2

/dev/null

Check existing Sentry

grep -i sentry package.json 2

/dev/null ls src/instrument.ts 2

/dev/null grep -r "Sentry.init|@sentry" src/main.ts src/instrument.ts 2

/dev/null

Check for existing Sentry DI wrapper (common in enterprise NestJS)

grep -rE "SENTRY.*TOKEN|SentryProxy|SentryService" src/ libs/ 2

/dev/null

Check for config-class-based init (vs env-var-based)

grep -rE "class SentryConfig|SentryConfig" src/ libs/ 2

/dev/null

Check if SentryModule.forRoot() is already registered in a shared module

grep -rE "SentryModule.forRoot|SentryProxyModule" src/ libs/ 2

/dev/null

Detect HTTP adapter (default is Express)

grep -E "FastifyAdapter|@nestjs/platform-fastify" package.json src/main.ts 2

/dev/null

Detect GraphQL

grep -E '"@nestjs/graphql"|"apollo-server"' package.json 2

/dev/null

Detect microservices

grep '"@nestjs/microservices"' package.json 2

/dev/null

Detect WebSockets

grep -E '"@nestjs/websockets"|"socket.io"' package.json 2

/dev/null

Detect task queues / scheduled jobs

grep -E '"@nestjs/bull"|"@nestjs/bullmq"|"@nestjs/schedule"|"bullmq"|"bull"' package.json 2

/dev/null

Detect databases

grep -E '"@prisma/client"|"typeorm"|"mongoose"|"pg"|"mysql2"' package.json 2

/dev/null

Detect AI libraries

grep -E '"openai"|"@anthropic-ai"|"langchain"|"@langchain"|"@google/generative-ai"|"ai"' package.json 2

/dev/null

Check for companion frontend

ls -d .. /frontend .. /web .. /client .. /ui 2

/dev/null 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: Feature Recommend when... Reference Error Monitoring Always — non-negotiable baseline ${SKILL_ROOT}/references/error-monitoring.md Tracing Always — NestJS lifecycle is auto-instrumented ${SKILL_ROOT}/references/tracing.md Profiling Production + CPU-sensitive workloads ${SKILL_ROOT}/references/profiling.md Logging Always; enhanced for structured log aggregation ${SKILL_ROOT}/references/logging.md Metrics Custom business KPIs or SLO tracking ${SKILL_ROOT}/references/metrics.md Crons @nestjs/schedule , Bull, or BullMQ detected ${SKILL_ROOT}/references/crons.md AI Monitoring OpenAI/Anthropic/LangChain/etc. detected ${SKILL_ROOT}/references/ai-monitoring.md Propose: "I recommend Error Monitoring + Tracing + Logging. Want Profiling, Crons, or AI Monitoring too?" Phase 3: Guide Install

Core SDK (always required — includes @sentry/node)

npm install @sentry/nestjs

With profiling support (optional)

npm install @sentry/nestjs @sentry/profiling-node ⚠️ 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 import * as Sentry from "@sentry/nestjs" ; // Optional: add profiling // import { nodeProfilingIntegration } from "@sentry/profiling-node"; Sentry . init ( { dsn : process . env . SENTRY_DSN , environment : process . env . SENTRY_ENVIRONMENT ?? "production" , release : process . env . SENTRY_RELEASE , sendDefaultPii : true , // Tracing — lower to 0.1–0.2 in high-traffic production tracesSampleRate : 1.0 , // Profiling (requires @sentry/profiling-node) // integrations: [nodeProfilingIntegration()], // profileSessionSampleRate: 1.0, // profileLifecycle: "trace", // Structured logs (SDK ≥ 9.41.0) enableLogs : true , } ) ; 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: import * as Sentry from "@sentry/nestjs" ; import { loadConfiguration } from "./config" ; const config = loadConfiguration ( ) ; Sentry . init ( { dsn : config . sentry . dsn , environment : config . sentry . environment ?? "production" , release : config . sentry . release , sendDefaultPii : config . sentry . sendDefaultPii ?? true , tracesSampleRate : config . sentry . tracesSampleRate ?? 1.0 , profileSessionSampleRate : config . sentry . profilesSampleRate ?? 1.0 , profileLifecycle : "trace" , enableLogs : true , } ) ; When adding new SDK options (e.g. sendDefaultPii , profileSessionSampleRate ), add them to the config type so they can be configured per environment. Step 2: Import instrument.ts FIRST in src/main.ts // instrument.ts MUST be the very first import — before NestJS or any other module import "./instrument" ; import { NestFactory } from "@nestjs/core" ; import { AppModule } from "./app.module" ; async function bootstrap ( ) { const app = await NestFactory . create ( AppModule ) ; // Enable graceful shutdown — flushes Sentry events on SIGTERM/SIGINT app . enableShutdownHooks ( ) ; await app . listen ( 3000 ) ; } bootstrap ( ) ; 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 import { Module } from "@nestjs/common" ; import { APP_FILTER } from "@nestjs/core" ; import { SentryModule , SentryGlobalFilter } from "@sentry/nestjs/setup" ; import { AppController } from "./app.controller" ; import { AppService } from "./app.service" ; @ Module ( { imports : [ SentryModule . forRoot ( ) , // Registers SentryTracingInterceptor globally ] , controllers : [ AppController ] , providers : [ AppService , { provide : APP_FILTER , useClass : SentryGlobalFilter , // Captures all unhandled exceptions } , ] , } ) export class AppModule { } 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: // instrument.mjs import * as Sentry from "@sentry/nestjs" ; Sentry . init ( { dsn : process . env . SENTRY_DSN , tracesSampleRate : 1.0 , } ) ; // package.json { "scripts" : { "start" : "node --import ./instrument.mjs -r ts-node/register src/main.ts" } } Or via environment: NODE_OPTIONS = "--import ./instrument.mjs" npm run start 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 import { Catch , ExceptionFilter , ArgumentsHost } from "@nestjs/common" ; import { SentryExceptionCaptured } from "@sentry/nestjs" ; @ Catch ( ) export class YourExistingFilter implements ExceptionFilter { @ SentryExceptionCaptured ( ) // Wraps catch() to auto-report exceptions catch ( exception : unknown , host : ArgumentsHost ) : void { // Your existing error handling continues unchanged } } Option C: Specific exception type — manual capture import { ArgumentsHost , Catch } from "@nestjs/common" ; import { BaseExceptionFilter } from "@nestjs/core" ; import * as Sentry from "@sentry/nestjs" ; @ Catch ( ExampleException ) export class ExampleExceptionFilter extends BaseExceptionFilter { catch ( exception : ExampleException , host : ArgumentsHost ) { Sentry . captureException ( exception ) ; super . catch ( exception , host ) ; } } Option D: Microservice RPC exceptions import { Catch , RpcExceptionFilter , ArgumentsHost } from "@nestjs/common" ; import { Observable , throwError } from "rxjs" ; import { RpcException } from "@nestjs/microservices" ; import * as Sentry from "@sentry/nestjs" ; @ Catch ( RpcException ) export class SentryRpcFilter implements RpcExceptionFilter < RpcException

{ catch ( exception : RpcException , host : ArgumentsHost ) : Observable < any

{ Sentry . captureException ( exception ) ; return throwError ( ( ) => exception . getError ( ) ) ; } } Decorators @SentryTraced(op?) — Instrument any method import { Injectable } from "@nestjs/common" ; import { SentryTraced } from "@sentry/nestjs" ; @ Injectable ( ) export class OrderService { @ SentryTraced ( "order.process" ) async processOrder ( orderId : string ) : Promise < void

{ // Automatically wrapped in a Sentry span } @ SentryTraced ( ) // Defaults to op: "function" async fetchInventory ( ) { ... } } @SentryCron(slug, config?) — Monitor scheduled jobs import { Injectable } from "@nestjs/common" ; import { Cron } from "@nestjs/schedule" ; import { SentryCron } from "@sentry/nestjs" ; @ Injectable ( ) export class ReportService { @ Cron ( "0 * * * " ) @ SentryCron ( "hourly-report" , { // @SentryCron must come AFTER @Cron schedule : { type : "crontab" , value : "0 * * * " } , checkinMargin : 2 , // Minutes before marking missed maxRuntime : 10 , // Max runtime in minutes timezone : "UTC" , } ) async generateReport ( ) { // Check-in sent automatically on start/success/failure } } Background Job Scope Isolation Background jobs share the default isolation scope — wrap with Sentry.withIsolationScope() to prevent cross-contamination: import * as Sentry from "@sentry/nestjs" ; import { Injectable } from "@nestjs/common" ; import { Cron , CronExpression } from "@nestjs/schedule" ; @ Injectable ( ) export class JobService { @ Cron ( CronExpression . EVERY_HOUR ) handleCron ( ) { Sentry . withIsolationScope ( ( ) => { Sentry . setTag ( "job" , "hourly-sync" ) ; this . doWork ( ) ; } ) ; } } 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. import { Controller , Inject } from "@nestjs/common" ; import { SENTRY_PROXY_TOKEN , type SentryProxyService } from "./sentry-proxy" ; @ Controller ( "orders" ) export class OrderController { constructor ( @ Inject ( SENTRY_PROXY_TOKEN ) private readonly sentry : SentryProxyService , private readonly orderService : OrderService , ) { } @ Post ( ) async createOrder ( @ Body ( ) dto : CreateOrderDto ) { return this . sentry . startSpan ( { name : "createOrder" , op : "http" } , async ( ) => this . orderService . create ( dto ) , ) ; } } 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: import { Controller , Get } from "@nestjs/common" ; import * as Sentry from "@sentry/nestjs" ; @ Controller ( ) export class DebugController { @ Get ( "/debug-sentry" ) triggerError ( ) { throw new Error ( "My first Sentry error from NestJS!" ) ; } @ Get ( "/debug-sentry-span" ) triggerSpan ( ) { return Sentry . startSpan ( { op : "test" , name : "NestJS Test Span" } , ( ) => { return { status : "span created" } ; } ) ; } } 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: Feature Reference file Load when... Error Monitoring ${SKILL_ROOT}/references/error-monitoring.md Always (baseline) Tracing ${SKILL_ROOT}/references/tracing.md Always (NestJS routes are auto-traced) Profiling ${SKILL_ROOT}/references/profiling.md CPU-intensive production apps Logging ${SKILL_ROOT}/references/logging.md Structured log aggregation needed Metrics ${SKILL_ROOT}/references/metrics.md Custom KPIs / SLO tracking Crons ${SKILL_ROOT}/references/crons.md Scheduled jobs or task queues AI Monitoring ${SKILL_ROOT}/references/ai-monitoring.md OpenAI/Anthropic/LangChain detected For each feature: Read ${SKILL_ROOT}/references/.md , follow steps exactly, verify it works. Configuration Reference Key Sentry.init() Options Option Type Default Purpose dsn string — SDK disabled if empty; env: SENTRY_DSN environment string "production" e.g., "staging" ; env: SENTRY_ENVIRONMENT release string — e.g., "myapp@1.0.0" ; env: SENTRY_RELEASE sendDefaultPii boolean false Include IP addresses and request headers tracesSampleRate number — Transaction sample rate; undefined disables tracing tracesSampler function — Custom per-transaction sampling (overrides rate) tracePropagationTargets Array — URLs to propagate sentry-trace / baggage headers to profileSessionSampleRate number — Continuous profiling session rate (SDK ≥ 10.27.0) profileLifecycle "trace"|"manual" "trace" "trace" = auto-start profiler with spans; "manual" = call startProfiler() / stopProfiler() enableLogs boolean false Send structured logs to Sentry (SDK ≥ 9.41.0) ignoreErrors Array [] Error message patterns to suppress ignoreTransactions Array [] Transaction name patterns to suppress beforeSend function — Hook to mutate or drop error events beforeSendTransaction function — Hook to mutate or drop transaction events beforeSendLog function — Hook to mutate or drop log events debug boolean false Verbose SDK debug output maxBreadcrumbs number 100 Max breadcrumbs per event Environment Variables Variable Maps to Notes SENTRY_DSN dsn Used if dsn not passed to init() SENTRY_RELEASE release Also auto-detected from git SHA, Heroku, CircleCI SENTRY_ENVIRONMENT environment Falls back to "production" SENTRY_AUTH_TOKEN CLI/source maps For npx @sentry/wizard@latest -i sourcemaps SENTRY_ORG CLI/source maps Organization slug SENTRY_PROJECT CLI/source maps Project slug Auto-Enabled Integrations These integrations activate automatically when their packages are detected — no integrations: [...] needed: Auto-enabled Notes httpIntegration Outgoing HTTP calls via http / https / fetch expressIntegration Express adapter (default NestJS) nestIntegration NestJS lifecycle (middleware, guards, pipes, interceptors, handlers) onUncaughtExceptionIntegration Uncaught exceptions onUnhandledRejectionIntegration Unhandled promise rejections openAIIntegration OpenAI SDK (when installed) anthropicAIIntegration Anthropic SDK (when installed) langchainIntegration LangChain (when installed) graphqlIntegration GraphQL (when graphql package present) postgresIntegration pg driver mysqlIntegration mysql / mysql2 mongoIntegration MongoDB / Mongoose redisIntegration ioredis / redis Integrations Requiring Manual Setup Integration When to add Code nodeProfilingIntegration Profiling desired import { nodeProfilingIntegration } from "@sentry/profiling-node" prismaIntegration Prisma ORM used integrations: [Sentry.prismaIntegration()] consoleLoggingIntegration Capture console output integrations: [Sentry.consoleLoggingIntegration()] localVariablesIntegration Capture local var values in errors integrations: [Sentry.localVariablesIntegration()] Verification Test that Sentry is receiving events: // Add a test endpoint (remove before production) @ Get ( "/debug-sentry" ) getError ( ) { throw new Error ( "My first Sentry error!" ) ; } Or send a test message without crashing: import * as Sentry from "@sentry/nestjs" ; Sentry . captureMessage ( "NestJS Sentry SDK test" ) ; If nothing appears: Set debug: true in Sentry.init() — prints SDK internals to stdout Verify SENTRY_DSN env var is set in the running process Check that import "./instrument" is the first line in main.ts Confirm SentryModule.forRoot() is imported in AppModule Check DSN format: https://@o.ingest.sentry.io/ Phase 4: Cross-Link After completing NestJS setup, check for a companion frontend missing Sentry: ls -d .. /frontend .. /web .. /client .. /ui 2

/dev/null cat .. /frontend/package.json .. /web/package.json 2

/dev/null \ | grep -E '"react"|"svelte"|"vue"|"next"|"nuxt"' If a frontend exists without Sentry, suggest the matching skill: Frontend detected Suggest skill Next.js sentry-nextjs-sdk React sentry-react-sdk Svelte / SvelteKit sentry-svelte-sdk Vue / Nuxt Use @sentry/vue — see docs.sentry.io/platforms/javascript/guides/vue/ React Native / Expo sentry-react-native-sdk Troubleshooting Issue Solution Events not appearing Set debug: true , verify SENTRY_DSN , check instrument.ts is imported first Malformed DSN error Format: https://@o.ingest.sentry.io/ Exceptions not captured Ensure SentryGlobalFilter is registered via APP_FILTER in AppModule Auto-instrumentation not working instrument.ts must be the first import in main.ts — before all NestJS imports Profiling not starting Requires tracesSampleRate > 0 + profileSessionSampleRate > 0 + @sentry/profiling-node installed enableLogs not working Requires SDK ≥ 9.41.0 No traces appearing Verify tracesSampleRate is set (not undefined ) Too many transactions Lower tracesSampleRate or use tracesSampler to drop health checks Fastify + GraphQL issues Known edge cases — see GitHub #13388 ; prefer Express for GraphQL Background job events mixed Wrap job body in Sentry.withIsolationScope(() => { ... }) Prisma spans missing Add integrations: [Sentry.prismaIntegration()] to Sentry.init() ESM syntax errors Set registerEsmLoaderHooks: false (disables ESM hooks; also disables auto-instrumentation for ESM modules) SentryModule breaks instrumentation Must import from @sentry/nestjs/setup , never from @sentry/nestjs RPC exceptions not captured Add dedicated SentryRpcExceptionFilter (see Option D in exception filter section) WebSocket exceptions not captured Use @SentryExceptionCaptured() on gateway handleConnection / handleDisconnect @SentryCron not triggering Decorator order matters — @SentryCron MUST come after @Cron TypeScript path alias issues Ensure tsconfig.json paths are configured so instrument resolves from main.ts location import * as Sentry ESLint error Many projects ban namespace imports. Use named imports ( import { startSpan, captureException } from "@sentry/nestjs" ) or use the project's DI proxy instead profilesSampleRate vs profileSessionSampleRate profilesSampleRate is deprecated in SDK 10.x. Use profileSessionSampleRate + profileLifecycle: "trace" instead Duplicate spans on every request SentryModule.forRoot() registered in multiple modules. Ensure it's only called once — check shared/library modules Config property not recognized in instrument.ts When using a typed config class, new SDK options must be added to the config type definition and the project rebuilt before TypeScript recognizes them Version Requirements Feature Minimum SDK Version @sentry/nestjs package 8.0.0 @SentryTraced decorator 8.15.0 @SentryCron decorator 8.16.0 Event Emitter auto-instrumentation 8.39.0 SentryGlobalFilter (unified) 8.40.0 Sentry.logger API ( enableLogs ) 9.41.0 profileSessionSampleRate 10.27.0 Node.js requirement ≥ 18 Node.js for ESM --import ≥ 18.19.0 NestJS compatibility 8.x – 11.x