Introduction

@eienjs/adonisjs-sentry provides seamless integration with the official Sentry Node SDK (@sentry/node) for AdonisJS v7 applications.

It simplifies error tracking and performance monitoring by automatically attaching HTTP context, route patterns, and user identity to captured exceptions, while isolating requests and grouping errors by AdonisJS error codes.

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

Key Features

• Automatic HTTP Context: Attaches HTTP method, route pattern, request ID, URL, and route params to captured events.
• Smart Error Grouping: Automatically fingerprints events by AdonisJS error code (E_*) so distinct error categories are never bundled together erroneously.
• Configurable Filtering: Easily ignore non-critical errors by HTTP status codes (e.g. 404, 422), error codes (e.g. E_ROUTE_NOT_FOUND), or custom exception classes.
• Request Scope Isolation: Dedicated router middleware ensures concurrent asynchronous requests never leak context or user data between each other.
• Performance Tracing: Integrates with Sentry spans, updates transaction names to match AdonisJS route patterns (e.g. GET /users/:id), and records route attributes.
• Privacy Controls: User IDs are captured by default while personally identifiable information (PII) such as email and IP address are withheld unless explicitly enabled.
• Health Verification: Built-in node ace sentry:verify command to test your connection and ensure events are flushed and delivered.
• Preloading Support: Seamlessly works with early preloading when full auto-instrumentation for third-party libraries (database drivers, Redis, HTTP clients) is needed.

Requirements

Before installing @eienjs/adonisjs-sentry, verify that your project meets the following requirements:

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

Next Steps

Head over to the Installation guide to install the package and set up error tracking in your project.