Nest.js

Learn how to set up Sentry in your Nest.js app and capture your first errors.

You need:

Choose the features you want to configure, and this guide will show you how:

Want to learn more about these features?
  • Issues (always enabled): Sentry's core error monitoring product that automatically reports errors, uncaught exceptions, and unhandled rejections. If you have something that looks like an exception, Sentry can capture it.
  • Tracing: Track software performance while seeing the impact of errors across multiple systems. For example, distributed tracing allows you to follow a request from the frontend to the backend and back.
  • Profiling: Gain deeper insight than traditional tracing without custom instrumentation, letting you discover slow-to-execute or resource-intensive functions in your app.

Run the command for your preferred package manager to add the Sentry SDK to your application:

Copied
npm install @sentry/nestjs @sentry/profiling-node --save

To import and initialize Sentry, create a file named instrument.ts in the root directory of your project and add the following code:

instrument.ts
Copied
const Sentry = require("@sentry/nestjs");
//  profiling
const { nodeProfilingIntegration } = require("@sentry/profiling-node");
//  profiling

// Ensure to call this before requiring any other modules!
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  //  profiling
  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  //  profiling
  //  performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/nestjs/configuration/options/#tracesSampleRate
  tracesSampleRate: 1.0,
  //  performance
  //  profiling

  // Set profilesSampleRate to 1.0 to profile 100%
  // of sampled transactions.
  // This is relative to tracesSampleRate
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/nestjs/configuration/options/#profilesSampleRate
  profilesSampleRate: 1.0,
  //  profiling
});

Make sure to import the instrument.ts file before any other modules:

main.ts
Copied
// Import this first!
import "./instrument";


// Now import other modules
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}

bootstrap();

Afterward, add the SentryModule as a root module to your main module:

app.module.ts
Copied
import { Module } from "@nestjs/common";

import { SentryModule } from "@sentry/nestjs/setup";

import { AppController } from "./app.controller";
import { AppService } from "./app.service";

@Module({
  imports: [

    SentryModule.forRoot(),

    // ...other modules
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

By default, Sentry only captures unhandled exceptions that aren't caught by an error filter. Additionally, HttpExceptions (including derivatives) aren't captured by default because they mostly act as control flow vehicles.

To make sure Sentry captures all your app's errors, configure error handling based on how your application manages exceptions:

If you have a global catch-all exception filter, add a @SentryExceptionCaptured() decorator to the filter's catch() method:

Copied
import { Catch, ExceptionFilter } from "@nestjs/common";

import { SentryExceptionCaptured } from "@sentry/nestjs";


@Catch()
export class YourCatchAllExceptionFilter implements ExceptionFilter {

  @SentryExceptionCaptured()

  catch(exception, host): void {
    // your implementation here
  }
}

If you don't have a global catch-all exception filter, add the SentryGlobalFilter to the providers of your main module, before any other exception filters:

Copied
import { Module } from "@nestjs/common";

import { APP_FILTER } from "@nestjs/core";
import { SentryGlobalFilter } from "@sentry/nestjs/setup";


@Module({
  providers: [

    {
      provide: APP_FILTER,
      useClass: SentryGlobalFilter,
    },

    // ..other providers
  ],
})
export class AppModule {}

If you have error filters for specific types of exceptions (for example, @Catch(HttpException)) and you want to report these errors to Sentry, you need to capture them in the catch() handler using Sentry.captureException():

Copied
import { ArgumentsHost, BadRequestException, Catch } from "@nestjs/common";
import { BaseExceptionFilter } from "@nestjs/core";
import { ExampleException } from "./example.exception";

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


@Catch(ExampleException)
export class ExampleExceptionFilter extends BaseExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {

    Sentry.captureException(exception);

    return super.catch(new BadRequestException(exception.message), host);
  }
}
Are you using Microservices?

If you're using @nestjs/microservices make sure to handle errors in RPC contexts correctly by providing your own RpcExceptionFilter (see Nest.js Microservices documentation). SentryGlobalFilter in a hybrid application doesn't extend BaseRpcExceptionFilter since this depends on @nestjs/microservices.

Use Sentry.captureException(exception) in your custom filter in case you want to send these errors to Sentry:

Copied
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 ExceptionFilter implements RpcExceptionFilter<RpcException> {
  catch(exception: RpcException, host: ArgumentsHost): Observable<any> {
    Sentry.captureException(exception); // optional
    return throwError(() => exception.getError());
  }
}

The stack traces in your Sentry errors probably won't look like your actual code. To fix this, upload your source maps to Sentry. The easiest way to do this is by using the Sentry Wizard:

Copied
npx @sentry/wizard@latest -i sourcemaps

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following route to your application, which will trigger an error that Sentry will capture:

Copied
@Get("/debug-sentry")
  getError() {
    throw new Error("My first Sentry error!");
  }

To test your tracing configuration, update the previous code snippet by starting a performance trace to measure the time it takes for the execution of your code:

Copied
@Get("/debug-sentry")
  getError() {
    Sentry.startSpan(
	  {
	    op: "test",
	    name: "My First Test Transaction",
	  },
	  () => {
	    setTimeout(() => {
	      throw new Error("My first Sentry error!");
	    }, 99);
	  },
	);
}

Now, head over to your project on Sentry.io to view the collected data (it takes a couple of moments for the data to appear).

Need help locating the captured errors in your Sentry project?
  1. Open the Issues page and select an error from the issues list to view the full details and context of this error. For an interactive UI walkthrough, click here.
  2. Open the Traces page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click here.
  3. Open the Profiles page, select a transaction, and then a profile ID to view its flame graph. For more information, click here.

At this point, you should have integrated Sentry into your Nest.js application and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:

Are you having problems setting up the SDK?
Previous
Welcome to Sentry
Next
Installation Methods
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").