Early Preloading

By default, @eienjs/adonisjs-sentry initializes Sentry during the provider's register() lifecycle hook.

While this captures all unhandled exceptions and route-level spans, some third-party libraries (such as database drivers pg/mysql2, Redis clients ioredis, or HTTP clients) require Sentry to be initialized before those modules are first imported by Node.js in order to automatically instrument their queries and network calls.

How Early Preloading Works

AdonisJS provides a preloads mechanism in adonisrc.ts that runs modules at the very start of the boot cycle before providers and application code are registered.

When Sentry is initialized in a preload file, SentryProvider detects that Sentry.isInitialized() is already true. The provider gracefully skips calling Sentry.init(...) again, configures the exception reporting rules from config/sentry.ts, and retains ownership of the graceful shutdown hook.

Setup Instructions

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

if (app.inProduction && env.get('SENTRY_DSN')) {
  Sentry.init({
    dsn: env.get('SENTRY_DSN'),
    environment: app.nodeEnvironment,
    release: env.get('SENTRY_RELEASE'),
    tracesSampleRate: 0.2,
  });
}

export default defineConfig({
  preloads: [
    {
      file: () => import('#start/sentry'),
      environment: ['web', 'console'],
    },
    // ... other preloads
  ],
  // ...
});