CommonJS (CJS)

Learn about running Sentry in an CJS application.

Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. CommonJS uses require() to load modules. Our recommended installation method when using CommonJS is to require the instrument.js file at the top of your application.

You need to create a file named instrument.js that imports and initializes Sentry:

instrument.mjs
Copied
import * as Sentry from "@sentry/nestjs";
//  profiling
import { nodeProfilingIntegration } from "@sentry/profiling-node";
//  profiling

// Ensure to call this before importing any other modules!
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/guides/nestjs/configuration/options/#sendDefaultPii
  sendDefaultPii: true,

  //  profiling
  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  //  profiling
  //  performance

  // Add Tracing by setting tracesSampleRate
  // We recommend adjusting this value in production
  tracesSampleRate: 1.0,
  //  performance
  //  profiling

  // Set sampling rate for profiling
  // This is relative to tracesSampleRate
  profilesSampleRate: 1.0,
  //  profiling
});

You need to require or import the instrument.js file before requiring any other modules in your application. This is necessary to ensure that Sentry can automatically instrument all modules in your application:

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();

Afterwards, 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 {}

If you're using a global catch-all exception filter (which is either a filter registered with app.useGlobalFilters() or a filter registered in your app module providers annotated with a @Catch() decorator without arguments), add a @SentryExceptionCaptured() decorator to the filter's catch() method. This decorator will report all unexpected errors that are received by your global error filter to Sentry:

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
  }
}

By default, only unhandled exceptions that are not caught by an error filter are reported to Sentry. HttpExceptions (including derivatives) are also not captured by default because they mostly act as control flow vehicles.

If you don't have a global catch-all exception filter, add the SentryGlobalFilter to the providers of your main module. This filter will report any unhandled errors that aren't caught by other error filters to Sentry. Important: The SentryGlobalFilter needs to be registered 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 {}
Using Microservices?

If you are using @nestjs/microservices make sure to handle errors in RPC contexts correctly by providing your own RpcExceptionFilter (see https://docs.nestjs.com/microservices/exception-filters). SentryGlobalFilter in a hybrid application does not 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());
  }
}

If you have error filters for specific types of exceptions (for example @Catch(HttpException), or any other @Catch(...) with arguments) and you want to capture errors caught by these filters, capture the errors in the catch() handler with 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)
  }
}
Previous
Installation Methods
Next
ESM (MJS)
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").