AdonisJS

The Monocle agent instruments your AdonisJS application with OpenTelemetry. Once it is installed, HTTP requests, database queries, Redis calls, outgoing HTTP calls, emails, queue jobs, Ace commands, logs, and exceptions are traced automatically.

Prerequisites

• AdonisJS 6.2.0+ or 7.0.0+
• A Monocle project with a service. See Core concepts if you are not sure what that means.

Installation

1. Add the agent

   node ace add @monocle.sh/adonisjs-agent

   What this command does

   1. Creates the config/monocle.ts configuration file
   2. Creates the otel.ts initialization file at the project root
   3. Adds import '../otel.js' as the first import of bin/server.ts and bin/console.ts
   4. Registers the Monocle provider in adonisrc.ts
   5. Registers the Monocle middleware as the first router middleware
   6. Adds APP_ENV and MONOCLE_DSN to .env and their validators to start/env.ts
2. Copy your DSN

   In Monocle, open Services, select your service, pick AdonisJS under SDK connection, then click Create DSN. You can copy it again from the same page at any time.

   MONOCLE_DSN=https://mk_live_xxxxxxxx@ingest.monocle.sh/00000000-0000-4000-8000-000000000001

3. Deploy and make a request

   Set the same variables in your production environment, deploy, and hit any route. The request shows up in Monocle within a few seconds, under the environment set by APP_ENV.

Environment variables

The configurator generates only APP_ENV and MONOCLE_DSN. It does not generate or require APP_NAME or APP_VERSION.

With a DSN, the collector uses the name of the service attached to that DSN. In Studio, without a DSN, or for extra OTLP destinations, the name comes from serviceName, then OTEL_SERVICE_NAME, then APP_NAME, then the app's package.json name without its npm scope. For example, @acme/api becomes api. If none is available, the name is unknown_service.

Existing apps need no change. Their config and validators still work, and an APP_VERSION=0.0.1 placeholder lets automatic detection take over.

Next steps