Configuration

The agent reads config/unhandled.ts, whose default export is the result of defineConfig from @unhandled/agent-adonisjs. This page lists each option with its default, then the rules the agent follows to decide whether to export and where. Every option is optional.

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'),
})

Connection

Signals and export

batch configures both the span and the log record batch processors. Pass only the keys you change. The rest keep their defaults.

Sampling

Setting sampling forces samplingRatio to 1. Job sampling can decide to keep a failed job after it ends, and that only works when every trace was recorded.

Built-in instrumentations

mail, queue and cli also take false or { enabled: false }. Mail, queue and Ace commands has the details.

Integrations

Optional instrumentations ship as separate packages. Register each one in integrations:

import env from '#start/env'
import { defineConfig } from '@unhandled/agent-adonisjs'
import { bullmq } from '@unhandled/instrumentation-bullmq/integration'
import { bentocache } from '@unhandled/instrumentation-bentocache/integration'

export default defineConfig({
  dsn: env.get('UNHANDLED_DSN'),
  environment: env.get('APP_ENV'),
  integrations: [bullmq(), bentocache()],
})

An integration missing from the list records nothing. When one fails during startup, the agent throws an IntegrationSetupError whose message names it. The packages: BullMQ, Bentocache, Vercel AI and Mastra.

Removed options

Version 2.0 removed four top-level options. Passing one throws an UnhandledConfigError that names its replacement package.

Exceptions

These filters cover only errors that reach the Adonis exception handler. Unhandled.captureException sends regardless. See Users and exceptions.

Options from @unhandled/node

The agent is a thin layer on @unhandled/node. Its config type extends the Node SDK options, and the agent passes them straight through. The common ones:

Options on the Node SDK page lists every one. userContext is the only option the agent adds. It controls automatic user extraction in the middleware: the user id and role by default, the email only with userContext: { email: true }, and nothing with false.

Instrumentation entries

Each instrumentations entry takes one of three shapes:

• A config object. It merges with the built-in config for that package.
• An Instrumentation instance. It replaces the built-in instrumentation.
• { enabled: false }. It turns the instrumentation off.

The @opentelemetry/instrumentation-http entry also accepts ignoredUrls, mergeIgnoredUrls, ignoreStaticFiles and ignoreOptionsRequests. A config object there keeps the agent's ignored URLs and outgoing body capture. Your ignoreIncomingRequestHook, requestHook and responseHook run alongside the built-in ones.

DSN

A DSN has this shape:

https://[email protected]/0b4f6c2e-8a1d-4c3e-9f7a-1234567890ab

A password, a query string or a fragment makes the DSN invalid. With a valid DSN, every export carries x-api-key, x-unhandled-service-id and x-unhandled-env, the last one set to the resolved environment.

Moving from apiKey to dsn

Older setups pass apiKey, endpoint and serviceName. They still work, and the agent sends x-api-key and x-unhandled-env to endpoint. Move one service at a time:

When both dsn and apiKey are set, dsn wins. An endpoint set next to dsn replaces the DSN host, and the DSN still supplies the key and the service.

Turning export off

The agent exports nothing in the cases below. It also skips starting the SDK, unless debug is on.

In the no-DSN and dev-mode cases, extra destinations still receive data. They are separate targets.

Extra destinations

Send the same traces, logs and metrics to a second OTLP backend:

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

export default defineConfig({
  dsn: env.get('UNHANDLED_DSN'),
  environment: env.get('APP_ENV'),
  serviceName: 'shop-api',
  destinations: [
    destinations.otlp({
      name: 'collector',
      url: 'https://otel-collector.internal:4318',
      headers: { authorization: 'Bearer <collector-token>' },
    }),
  ],
})

destinations.otlp takes:

Each destination uses the shared compression and batch settings. The agent always keeps the Unhandled destination built from the DSN and adds the extra ones next to it.

Service name and version

With a DSN, Unhandled takes the service from the DSN. The local name matters for extra destinations, dev mode and legacy setups. The agent takes the first of:

1. serviceName
2. OTEL_SERVICE_NAME
3. APP_NAME
4. The name in package.json, minus its npm scope (@shop/api becomes api)
5. unknown_service

For the version, it takes the first usable value of:

1. serviceVersion
2. UNHANDLED_VERSION
3. APP_VERSION
4. A platform revision from Vercel, Render, Railway, Heroku, Coolify, Dokku or Cloud Run
5. A CI commit from GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines or Buildkite
6. The HEAD commit in the local .git directory

0.0.0, 0.0.1, 1.0.0, unknown, dev, latest and empty strings count as placeholders, and the agent skips them. So serviceVersion: env.get('APP_VERSION') is safe. If the variable holds 0.0.1, the agent moves to the next source.

Every signal carries these resource attributes: