Getting Started

Configuration

Customize Sentry options, sampling rates, PII settings, and exception ignore lists in config/sentry.ts.

The configuration for @eienjs/adonisjs-sentry is located in config/sentry.ts. It uses the defineConfig helper to ensure type safety and validate essential options before the application boots.

Default Configuration

config/sentry.ts

import app from '@adonisjs/core/services/app';
import { defineConfig } from '@eienjs/adonisjs-sentry';
import env from '#start/env';

const sentryConfig = defineConfig({
  /**
   * Enable or disable Sentry
   */
  enabled: app.inProduction,

  /**
   * The environment Sentry is running in
   */
  environment: app.nodeEnvironment,

  /**
   * The DSN of the project
   */
  dsn: env.get('SENTRY_DSN'),

  /**
   * The release identifier, used to match events with source maps
   * @see https://docs.sentry.io/platforms/javascript/guides/node/configuration/releases
   */
  release: env.get('SENTRY_RELEASE'),

  /**
   * Additional integrations to use with the Sentry SDK
   * @see https://docs.sentry.io/platforms/javascript/guides/node/configuration/integrations/#available-integrations
   */
  integrations: [],

  /**
   * Do not send personally identifiable information (email, IP) by default
   * @see https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#dataCollection
   */
  dataCollection: {
    userInfo: false,
  },

  /**
   * The sample rate of traces to send to Sentry
   * @see https://docs.sentry.io/platforms/javascript/guides/node/configuration/sampling
   */
  tracesSampleRate: 0.2,

  /**
   * Control which exceptions are reported to Sentry.
   */
  report: {
    ignoreStatuses: [],
    ignoreCodes: [],
    ignoreExceptions: [],
    captureUser: true,
    fingerprintByCode: true,
  },
});

export default sentryConfig;

Validation Rules

When defineConfig evaluates your configuration object, it performs two critical runtime checks:

environment is required: If missing or empty, RuntimeException is thrown.
dsn is required when enabled is true: If enabled: true and dsn is missing or undefined, RuntimeException is thrown.
If enabled is false, dsn can safely be omitted or left blank.

Configuration Options

Top-Level Options

Option	Type	Default	Description
`enabled`	`boolean`	`app.inProduction`	Toggles Sentry SDK initialization and exception reporting.
`environment`	`string`	`app.nodeEnvironment`	The environment name (e.g. `production`, `staging`, `development`).
`dsn`	`string`	`env.get('SENTRY_DSN')`	The Sentry Data Source Name. Required when `enabled` is `true`.
`release`	`string`	`env.get('SENTRY_RELEASE')`	Release identifier matching events with uploaded source maps.
`integrations`	`Integration[]`	`[]`	Additional integrations from `@sentry/node`.
`dataCollection`	`{ userInfo: boolean }`	`{ userInfo: false }`	When `userInfo: false`, user email and IP addresses are stripped for PII compliance.
`tracesSampleRate`	`number`	`0.2`	Percentage of performance traces captured (between `0.0` and `1.0`).

SentryConfig extends Sentry's native NodeOptions (omitting dsn and environment). You can pass any standard Sentry Node configuration option here, such as beforeSend, maxBreadcrumbs, debug, or sampleRate.

`report` Options

The report property controls exception capture behavior when invoking reportException(error, ctx):

Option	Type	Default	Description
`report.ignoreStatuses`	`number[]`	`[]`	HTTP status codes that will not be sent to Sentry (e.g. `[404, 422]`).
`report.ignoreCodes`	`string[]`	`[]`	Adonis error codes that will not be sent to Sentry (e.g. `['E_ROUTE_NOT_FOUND']`).
`report.ignoreExceptions`	`ExceptionConstructor[]`	`[]`	Exception classes checked via `instanceof` to ignore.
`report.captureUser`	`boolean`	`true`	Whether to attach `ctx.auth.user` to the Sentry event scope.
`report.fingerprintByCode`	`boolean`	`true`	Group Sentry issues by Adonis error code (`E_*`) instead of raw error message.

Example: Ignoring Common HTTP Errors

In production, you usually want to avoid filling your Sentry quota with client-side validation errors (422) or missing routes (404):

config/sentry.ts

import { errors as authErrors } from '@adonisjs/auth';
import { errors as coreErrors } from '@adonisjs/core';
import { defineConfig } from '@eienjs/adonisjs-sentry';

export default defineConfig({
  // ... other options
  report: {
    ignoreStatuses: [404, 422],
    ignoreCodes: [
      'E_ROUTE_NOT_FOUND',
      'E_VALIDATION_ERROR',
      'E_INVALID_AUTH_SESSION',
    ],
    ignoreExceptions: [
      coreErrors.E_ROUTE_NOT_FOUND,
      authErrors.E_UNAUTHORIZED_ACCESS,
    ],
    captureUser: true,
    fingerprintByCode: true,
  },
});

To learn more about how reporting works under the hood, see Exception Reporting.

Installation

Install and configure @eienjs/adonisjs-sentry in your AdonisJS v7 application.

Exception Reporting

Capture, enrich, and filter exceptions with HTTP context, user details, and smart fingerprinting.