npm package: @geekbears/gb-nest-sentry
Description: A NestJS module for Sentry
Author: It Geekbears
Latest version: 1.0.8
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

<h1 align="center">GbNestSentry</h1>

<div align="center">
  <a href="http://nestjs.com/" target="_blank">
    <img src="https://nestjs.com/img/logo_text.svg" width="150" alt="Nest Logo" />
  </a>
</div>

<h3 align="center">A NestJS module for <a href="http://sentry.io/">Sentry</a> with support for error reporting and operation tracing.</h3>

<div align="center">
  <a href="https://nestjs.com" target="_blank">
    <img src="https://img.shields.io/badge/built%20with-NestJs-red.svg" alt="Built with NestJS">
  </a>
  <a href="https://github.com/nestjsplus/dyn-schematics" target="_blank">
    <img src="https://img.shields.io/badge/Built%20with-%40nestjsplus%2Fdyn--schematics-brightgreen" alt="Built with @nestjsplus/dyn-schematics">
  </a>
</div>

## Instalation

To install this package, you must have a reference to the `@geekbears` repository on your `npmrc`.

Run the following command to install the NestJS module along with the required dependencies

```bash
npm install --save @geekbears/gb-nest-sentry @sentry/node @sentry/tracing
```

## Usage

Once installed, configure the module provider on your application's root module:

```typescript
GbNestModule.forRoot({
  dsn: '<dsn>',
  environment: '<env>',
  ...
}),
```

Alternatively, an async factory can be used:

```typescript
GbNestModule.forRootAsync({
  inject: [],
  useFactory: () => ({
    dsn: '<dsn>',
    environment: '<env>',
    ...
  }),
}),
```

### Options

The module uses the default `NodeOptions` interface exposed by `@sentry/node` to configure the Sentry instance.

For more details regarding supported options, please refer to the [Sentry Documentation](https://docs.sentry.io/platforms/node/configuration/options/).

### Tracing

The module itself sets up a span for every operation, and database tracing can be configured by adding the corresponding integration to the configuration options. For example, a Mongoose connection can be traced by defining the following `integration` on the config object:

```typescript
import {Integrations} from '@sentry/node';

...

GbNestModule.forRoot({
  integrations: [new Integrations.Mongo({ useMongoose: true })]
}),
```

#### Manual Tracing

For more details regarding database tracing, please refer to the [Sentry Documentation](https://docs.sentry.io/platforms/node/performance/database/)

Additionally, manual tracing can be integrated by injecting the `SentryService` and then creating a new child span. The developer must ensure to handle the child span appropriately.

1. Import the injection decorator

```typescript
import { InjectSentry } from '@geekbears/gb-nest-sentry';
```

2. Inject the service wherever you need it

```typescript
constructor(@InjectSentry() private readonly sentryService: SentryService) {}
```

3. Start a new child span

```typescript
this.sentryService.startChild({ ... })
```

## Optimal configuration for Geekbears projects

Geekbears projects rely on NestJS's `ConfigService` and environment variables, by leveraging these features we can optimally integrate Sentry with the following configuration:

```typescript
GbSentryModule.forRootAsync({
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({
    dsn: config.get<string>('SENTRY_DSN'),
    environment: config.get<string>('NODE_ENV'),
    enabled: config.get('SENTRY_ENABLED') === 'true' ? true : false,
    tracesSampleRate: 1.0,
    integrations: [new Integrations.Mongo({ useMongoose: true })],
    // debug: true,
  }),
}),
```

Explanation:

-   The factorye requires injecting the `ConfigService` so every value can be read from environment variables.
-   The `dsn` and `environment` fields are mandatory.
-   The `enabled` flag is a useful way to reduce noise by ignoring certain environments or configs (such as testing on development).
-   Integrate Mongo tracing with the `useMongoose` flag

## Considerations

-   The current implementation for the `SentryService` uses a `REQUEST` scope. An improvement is already underway to support other contexts appart from HTTP