If you are already using @adonisjs/otel, switching to the Monocle agent is straightforward. The agent wraps @adonisjs/otel and provides the same API with additional capabilities.
1. Swap the package
node ace remove @adonisjs/otel
node ace add @monocle.sh/adonisjs-agent2. Rename the config file
Rename config/otel.ts to config/monocle.ts and replace defineConfig import:
- import { defineConfig } from '@adonisjs/otel'
+ import { defineConfig } from '@monocle.sh/adonisjs-agent'3. Update your imports
Replace all @adonisjs/otel imports with their Monocle equivalents:
- import { record, getCurrentSpan } from '@adonisjs/otel/helpers'
+ import { record, getCurrentSpan } from '@monocle.sh/adonisjs-agent/helpers'
- import { span, spanAll } from '@adonisjs/otel/decorators'
+ import { span, spanAll } from '@monocle.sh/adonisjs-agent/decorators'4. Add your connection settings
node ace add adds the required environment variables to .env and start/env.ts. Fill them in as described in the AdonisJS installation guide, then restart your app.
Why Monocle's helpers matter
The Monocle agent re-exports most helpers from @adonisjs/otel unchanged (getCurrentSpan, setAttributes, recordEvent, etc.). However, record, handleError, @span, and @spanAll are enhanced versions that add source code context extraction.
When an exception is caught by these helpers, the agent reads the actual source files from disk and attaches the surrounding lines of code to the span. This is what powers the source code preview of issues. You get the exact line that errored with surrounding context, without needing source maps.
The agent also fully serializes the error cause chain (Error.cause), including AggregateError children, so nested errors are never lost.
These enhancements only work when importing from @monocle.sh/adonisjs-agent. If you keep using @adonisjs/otel imports directly, you will get standard OpenTelemetry error recording without the extra context.