AdonisJS agent

@unhandled/agent-adonisjs is Unhandled's first-party package for AdonisJS. It exports traces, logs, metrics and exceptions from an AdonisJS app to Unhandled over OTLP/HTTP. It is built on @unhandled/node, which runs the OpenTelemetry Node SDK, so every Node SDK option works in config/unhandled.ts. The agent adds route names, the signed-in user, the exception handler hook, and spans for Ace commands, mail and @adonisjs/queue. Use it for an AdonisJS API, a queue worker or a full-stack app. Other Node.js frameworks have their own packages, listed under SDKs.

Requirements

• AdonisJS 6.2 or later, or AdonisJS 7.
• Node.js 24 or later.
• An Unhandled service and its DSN. Give each deployable (API, worker, web app) its own service. See Services.

Install

Already on @adonisjs/otel

Run one package, not both. When otel.ts starts @adonisjs/otel, the configure hook stops without changing any file. When the @adonisjs/otel provider is registered or its SDK is running, the agent's provider throws at boot and names both ways out.

You can keep the official @adonisjs/otel package and send its data to Unhandled, either with unhandledDestinations() and your DSN or with four OTEL_* variables. The setup dialog shows the variables under Already using @adonisjs/otel. Keep @adonisjs/otel explains both and lists what you give up compared to the agent.

Generated files

config/unhandled.ts:

import env from '#start/env'
import { defineConfig } from '@unhandled/agent-adonisjs'

export default defineConfig({
  dev: env.get('NODE_ENV') === 'development',
  dsn: env.get('UNHANDLED_DSN'),
  environment: env.get('APP_ENV'),
})

otel.ts:

import { init } from '@unhandled/agent-adonisjs/init'

await init(import.meta.dirname)

Keep otel.ts first

// Must stay the first import so auto-instrumentation can patch modules on load
import '../otel.js'
await import('reflect-metadata')
const { Ignitor, prettyPrintError } = await import('@adonisjs/core/ignitor')

That is the AdonisJS 7 starter kit's shape. Apps that came from AdonisJS 6 import reflect-metadata and @adonisjs/core statically after otel.js, and that works too: both shapes record request spans.

Environment variables

The agent skips placeholder versions such as 0.0.1 and falls back to your platform, CI or git commit. The full order is in Service name and version.

The agent reads these variables from the process environment, so a bad UNHANDLED_ENV throws UnhandledConfigError rather than failing start/env.ts. To validate the optional ones with the rest of your config, add them to start/env.ts:

UNHANDLED_ENV: Env.schema.enum.optional(['development', 'staging', 'production'] as const),
UNHANDLED_VERSION: Env.schema.string.optional(),

Local development

The generated config turns on dev when NODE_ENV is development. Dev mode ignores the DSN, so a laptop never writes into a production service. It exports only when you also set endpoint to a local OTLP collector or add an extra destination. Set debug: true to print spans to the console.

Under NODE_ENV=test the agent stays off unless you set enabled yourself.

What is recorded

After the install, with no other code:

• HTTP requests, as SERVER spans named after the route (GET /orders/:id) with http.route, adonis.route.name and the response status. See HTTP tracing.
• Database queries, ClickHouse calls through @clickhouse/client, Redis commands, outgoing HTTP calls and the other auto-instrumentations that @unhandled/node turns on. See What is recorded.
• Mail sent with @adonisjs/mail, @adonisjs/queue jobs and Ace commands. See Mail, queue and Ace commands.
• Exceptions from the Adonis exception handler and from failed Ace commands, with source lines and the cause chain. See Users and exceptions.
• Pino logs, Node runtime metrics, and host CPU, memory and network metrics.

Next steps