@monocle.sh/adonisjs-agent

Monocle agent for AdonisJS - sends telemetry to Monocle cloud.

Installation

npm install @monocle.sh/adonisjs-agent
# or
yarn add @monocle.sh/adonisjs-agent
# or
pnpm add @monocle.sh/adonisjs-agent

Configuration

Run the configure command to set up the agent automatically:

node ace configure @monocle.sh/adonisjs-agent

This will:

1. Create config/monocle.ts configuration file
2. Create otel.ts initialization file at project root
3. Add the otel.ts import as the first import in bin/server.ts
4. Register the Monocle provider in adonisrc.ts
5. Register the Monocle middleware as the first router middleware
6. Add required environment variables to .env and start/env.ts

After configuration, add your API key to .env:

MONOCLE_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

User Identification

To associate telemetry data with authenticated users, add Monocle.setUser() in your authentication middleware:

import type { NextFn } from '@adonisjs/core/types/http'
import type { HttpContext } from '@adonisjs/core/http'
import { Monocle } from '@monocle.sh/adonisjs-agent'

export default class SilentAuthMiddleware {
  async handle(ctx: HttpContext, next: NextFn) {
    await ctx.auth.check()

    if (ctx.auth.user) Monocle.setUser(ctx.auth.user)

    return next()
  }
}

Exception Tracking

Exceptions are automatically recorded in spans when thrown during a request. The agent hooks into AdonisJS's ExceptionHandler.report() method to capture exceptions with their stack traces.

If you want to manually capture exceptions in custom code:

import { Monocle } from '@monocle.sh/adonisjs-agent'

try {
  // your code
} catch (error) {
  Monocle.captureException(error, {
    user: { id: '123', email: '[email protected]' },
    tags: { component: 'payment' },
    extra: { orderId: 456 },
  })
  throw error
}

Configuration Options

The config/monocle.ts file supports the following options:

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

export default defineConfig({
  // Optional: Your Monocle API key
  apiKey: env.get('MONOCLE_API_KEY'),

  // Optional: Custom ingestion endpoint (for development)
  // endpoint: 'http://localhost:4318',

  // Service identification
  serviceName: env.get('APP_NAME'),
  serviceVersion: env.get('APP_VERSION'),
  environment: env.get('APP_ENV'),

  // Additional OTLP destinations (Monocle is always injected automatically)
  destinations: {
    grafana: destinations.otlp({
      endpoint: env.get('GRAFANA_OTLP_ENDPOINT'),
      signals: 'all',
    }),
  },

  // Host metrics (CPU, Memory, Network, etc.)
  // Set to false to disable
  hostMetrics: {
    enabled: true,
  },

  // CLI command tracing
  cli: {
    enabled: false,
    exclude: ['make:*', 'generate:*', 'queue:work', 'queue:listen'],
  },

  // Trace/log batching configuration for Monocle destination
  batch: {
    maxExportBatchSize: 512,
    scheduledDelayMillis: 5000,
  },

  // Enable gzip compression for Monocle destination (default: true)
  compression: true,
})

Environment Variables

| Variable | Description | Required | | ----------------- | ------------------------------------------------------ | -------- | | MONOCLE_API_KEY | Your Monocle API key | No | | APP_NAME | Service name for identification | Yes | | APP_VERSION | Service version (e.g., git sha, semver) | Yes | | APP_ENV | Environment: development, staging, or production | Yes |

License

ISC