EienJS Logo
EienJS
Getting Started

Installation

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

Requirements

Ensure your environment satisfies the peer dependencies:

  • Node.js: >= 24.0.0
  • AdonisJS Core (@adonisjs/core): ^7.6.0
  • Sentry Node SDK (@sentry/node): ^11.12.0

Automated Installation

The fastest way to install and configure @eienjs/adonisjs-sentry is using the AdonisJS ace add command:

node ace add @eienjs/adonisjs-sentry

This single command will:

  1. Install @eienjs/adonisjs-sentry and @sentry/node using your project's package manager.
  2. Publish the config/sentry.ts configuration file.
  3. Append SENTRY_DSN and SENTRY_RELEASE to your .env and .env.example files.
  4. Define environment validation rules in start/env.ts.
  5. Register @eienjs/adonisjs-sentry/middleware/sentry_middleware in your router middleware stack.
  6. Register the provider and commands in your adonisrc.ts file.

Manual Installation

If you prefer installing packages manually, install @eienjs/adonisjs-sentry and its peer dependency @sentry/node:

pnpm add @eienjs/adonisjs-sentry @sentry/node

Then run the configure command:

node ace configure @eienjs/adonisjs-sentry

Step-by-Step Setup

1. Configure the Exception Handler

Open app/exceptions/handler.ts and call reportException inside the report method:

app/exceptions/handler.ts
import type { HttpContext } from '@adonisjs/core/http';
import { ExceptionHandler } from '@adonisjs/core/http';
import { reportException } from '@eienjs/adonisjs-sentry';

export default class HttpExceptionHandler extends ExceptionHandler {
  async report(error: unknown, ctx: HttpContext) {
    reportException(error, ctx);

    await super.report(error, ctx);
  }
}
reportException automatically checks whether Sentry is initialized and skips reporting if the exception matches any configured ignore lists.

2. Set Your Environment Variables

Add your Sentry project DSN to your .env file:

.env
SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
SENTRY_RELEASE=
SENTRY_DSN is only required when Sentry is enabled (by default in production). You can safely omit it in development or testing environments.

3. Verify the Integration

Execute the Ace verification command to test whether your application can deliver an event to Sentry:

node ace sentry:verify

If successful, the command prints the generated Sentry event ID. For more details on the verification command, see the Verify Command documentation.

What's Next?

Check out the Configuration guide to customize sampling rates, ignore filters, release tags, and privacy settings.

Introduction

Official Sentry integration for AdonisJS applications with automatic exception capture, request context, and distributed tracing.

Configuration

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