For AdonisJS 6 and 7

AdonisJS monitoring,
in one command.

Monocle traces every request, Lucid query, queue job, email, and Ace command of your AdonisJS app, with its logs and exceptions attached. Run node ace add, set one variable, deploy. No collector to run, no dashboard to build.

One command

node ace add, nothing else to wire

Every request traced

Named after its route, with its queries

Exceptions captured

Straight from your exception handler

Built on @adonisjs/otel

Standard OpenTelemetry

Out of the box

What Monocle monitors in your AdonisJS app

  • HTTP requests

    One trace per request, named after its route

  • Lucid queries

    Every query as a span, grouped by pattern

  • Redis and outgoing HTTP

    Each command and API call, in its request

  • Logger output

    ctx.logger lines linked to their trace

  • Exceptions

    Reported by your exception handler

  • @adonisjs/mail

    Every email sent, when installed

  • @adonisjs/queue

    Jobs from dispatch to execution

  • Ace commands

    With their arguments and flags

  • Host metrics

    CPU, memory, and network

One command, and your app reports

The agent installs like any AdonisJS package. Its configure hook writes the config, loads OpenTelemetry before your app boots, and registers the provider and the middleware for you.

  • Creates config/monocle.ts and otel.ts, and imports otel.ts first in bin/server.ts and bin/console.ts
  • Registers the Monocle provider and middleware, and adds MONOCLE_DSN and APP_ENV to your env
  • In development, telemetry goes to Monocle Studio on your machine, no DSN needed
config/monocle.ts
// node ace add @monocle.sh/adonisjs-agent
import { defineConfig } from '@monocle.sh/adonisjs-agent'
import env from '#start/env'

export default defineConfig({
  // Send telemetry to Monocle Studio instead of Monocle cloud
  dev: process.env.NODE_ENV === 'development',
  dsn: env.get('MONOCLE_DSN'),
  environment: env.get('APP_ENV'),
})

Every request, down to the query

Every HTTP request becomes a trace named after its route, like GET /users/:id. The Lucid queries, Redis commands, outgoing HTTP calls, and emails it triggers are nested inside, with their timing.

  • HTTP requests, Lucid queries, Redis commands, and outgoing HTTP calls
  • @adonisjs/mail emails and @adonisjs/queue jobs, as soon as the packages are installed
  • Ace commands with their arguments and flags, scaffolding commands left out

Logs and exceptions, tied to the request

Your AdonisJS logger output is sent with the trace and span that were active, so ctx.logger lines sit next to the request that wrote them. Exceptions reported by your exception handler become issues.

  • Hooks into ExceptionHandler.report(), and respects ignoreStatuses, ignoreCodes, and ignoreExceptions
  • Call Monocle.setUser() in your auth middleware, and every trace and issue knows its user
  • Repeated errors are grouped into one issue, with the stack trace and the users it hit

A dashboard for every part of your app

Requests are grouped by route, queries by pattern, jobs by name. Each one gets its dashboard the moment your app sends data, with nothing to build.

  • Endpoints with their 4xx, 5xx, and P95, and the slowest Lucid query patterns
  • Jobs with their queue wait and retries, Ace commands, and emails sent
  • CPU, memory, V8 heap, and event loop for each instance

Your own spans, when you need them

For business logic, wrap it in a span with the record() helper, or decorate a service. When something throws inside, the agent attaches the surrounding source code to the error.

  • record() handles sync and async callbacks and records exceptions for you
  • @span() and @spanAll() decorators for your services
  • Coming from @adonisjs/otel? The API is the same, only the import path changes
app/services/report_service.ts
import { record } from '@monocle.sh/adonisjs-agent/helpers'
import { span } from '@monocle.sh/adonisjs-agent/decorators'

export class ReportService {
  @span()
  async generate(userId: number) {
    const data = await record('report.load', () => load(userId))
    return render(data)
  }
}

Health checks your uptime monitor understands

Point an uptime monitor at the route that serves your AdonisJS health checks. Monocle reads the report and fails the check when your app says it is unhealthy, even on a 200 OK.

  • Reads the format of the AdonisJS health checks module as is
  • A check every minute, and an alert by email, Slack, Discord, or webhook
  • A public status page on your own domain
Works with

Plugs into your stack

AdonisJS 6 and 7

From 6.2.0, zero config

Lucid

Every query as a span

@adonisjs/mail & @adonisjs/queue

Traced when installed

BullMQ

Jobs from enqueue to run

Bentocache & @adonisjs/cache

Hits, misses, and latency

Kysely & Drizzle

Queries with readable SQL

Vercel AI SDK & Mastra

LLM calls, tokens, and costs

Browser SDK

Frontend errors linked to your API

Other OTLP backends

Send the same data to Grafana too

Early access

See what your apps
are really doing.

Traces, logs, errors and metrics for every app you ship. Bring it all into focus.