AdonisJS - monocle.sh

This guide covers everything you need to instrument your AdonisJS application with Monocle. You will learn how to:

Install and configure the agent
Track authenticated users across traces
Capture exceptions and custom messages
Use tracing helpers and decorators
Configure instrumentations (mail, cache, jobs, AI, MCP)
Fan out telemetry to multiple destinations

Overview

The agent includes Adonis instrumentation and the Node auto-instrumentation bundle. Add Mastra, Vercel AI, BullMQ, Bentocache, and MCP support explicitly so your application only installs the integrations it uses.

This guide uses @monocle.sh/adonisjs-agent 2.x. Upgrading from 1.x? Follow the migration guide.

Mail, Adonis queue, and Ace CLI tracing are built in. They activate automatically when their packages are available and keep their top-level mail, queue, and cli options. Optional mail and queue packages are resolved from your application; the agent does not install them.

Prerequisites

AdonisJS 6.2.0+ or AdonisJS 7.0.0+
A Monocle account with an API key

Installation

Install and configure the package using the Ace CLI.

node ace add @monocle.sh/adonisjs-agent

See what this command does

Creates config/monocle.ts configuration file
Creates otel.ts initialization file at project root
Adds the otel.ts import as the first import in bin/server.ts and bin/console.ts
Registers the Monocle provider in adonisrc.ts
Registers the Monocle middleware as the first router middleware
Adds required environment variables to .env and start/env.ts

After running the command, add your API key to .env:

.env

MONOCLE_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

You can find your API key in your application settings on the Monocle dashboard. That’s it. Your application now has automatic tracing for HTTP requests, database queries, Redis operations, and more.

The import order is critical.OpenTelemetry must initialize before any other code loads. The SDK needs to patch libraries like http, pg, and redis before they are imported. That is why otel.ts is imported as the very first line in bin/server.ts.If you move or remove the import '../otel.js' line, auto-instrumentation will not work.

Environment Variables

The agent requires these environment variables:

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

The APP_ENV variable determines which environment your telemetry data is associated with in Monocle. You can filter traces, logs, and metrics by environment using the environment selector in the dashboard.

Configuration

The configuration file is located at config/monocle.ts. Here is a minimal setup:

config/monocle.ts

import { defineConfig } from "@monocle.sh/adonisjs-agent";
import env from "#start/env";

export default defineConfig({
  apiKey: env.get("MONOCLE_API_KEY"),
  serviceName: env.get("APP_NAME"),
  serviceVersion: env.get("APP_VERSION"),
  environment: env.get("APP_ENV"),
});

Full configuration reference

All options are optional except apiKey, serviceName, serviceVersion, and environment.

config/monocle.ts

import { defineConfig } from "@monocle.sh/adonisjs-agent";
import env from "#start/env";

export default defineConfig({
  apiKey: env.get("MONOCLE_API_KEY"),
  serviceName: env.get("APP_NAME"),
  serviceVersion: env.get("APP_VERSION"),
  environment: env.get("APP_ENV"),

  // Custom ingestion endpoint (default: https://ingest.monocle.sh)
  endpoint: "https://ingest.monocle.sh",

  // Skip OPTIONS/CORS preflight requests (default: true)
  ignoreOptionsRequests: true,

  // Enable gzip compression (default: true)
  compression: true,

  // Trace batching configuration
  batch: {
    maxExportBatchSize: 512,
    scheduledDelayMillis: 5000,
    exportTimeoutMillis: 30000,
    maxQueueSize: 2048,
  },

  // Host metrics: CPU, memory, network (default: enabled)
  hostMetrics: {
    enabled: true,
  },

  // Sampling ratio (0.0 to 1.0). Use 0.1 for high-traffic production.
  // Default: 1.0 (100% of traces sampled)
  samplingRatio: 1.0,

  // Adonis features (enabled by default when the corresponding libraries are available)
  mail: { enabled: true },
  queue: { enabled: true },
  cli: { enabled: true },

  // Install and register optional integrations below as needed
  integrations: [],
});

Customizing instrumentations

You can configure individual OpenTelemetry instrumentations by passing options keyed by their package name.

config/monocle.ts

export default defineConfig({
  // ...

  instrumentations: {
    "@opentelemetry/instrumentation-http": {
      // Add URLs to ignore (merged with defaults by default)
      ignoredUrls: ["/internal/*", "/api/ping"],

      // Set to false to replace default ignored URLs instead of merging
      mergeIgnoredUrls: true,

      // Ignore static files like css, js, images (default: true)
      ignoreStaticFiles: true,
    },

    // Disable a specific instrumentation entirely
    "@opentelemetry/instrumentation-pg": { enabled: false },
  },
});

Default ignored URLs include /health, /healthz, /ready, /readiness, /metrics, /favicon.ico and other common health check paths.

User Context

To associate telemetry data with authenticated users, call Monocle.setUser() in your authentication middleware. This lets you filter traces and exceptions by user in the dashboard.

app/middleware/silent_auth_middleware.ts

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({
        id: ctx.auth.user.id,
        email: ctx.auth.user.email,
        name: ctx.auth.user.fullName,
      });
    }

    return next();
  }
}

The name field takes priority in the Monocle UI, falling back to email, then id.

Do not include sensitive data (passwords, tokens, API keys) in user attributes. These values are sent to Monocle and will be visible in trace viewers.

Exception Tracking

Exceptions thrown during a request are automatically captured by the agent. It hooks into AdonisJS’s ExceptionHandler.report() method and respects your ignore rules (ignoreExceptions, ignoreStatuses, ignoreCodes).

Manual exception capture

You can manually capture exceptions anywhere in your code.

app/services/payment_service.ts

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

try {
  await processPayment(order);
} catch (error) {
  Monocle.captureException(error, {
    user: { id: "123", email: "user@example.com" },
    tags: { component: "payment" },
    extra: { orderId: order.id, amount: order.total },
  });
  throw error;
}

Capture messages

Use Monocle.captureMessage() to capture custom messages when you want to track something that is not an exception. Messages appear in the Exceptions dashboard alongside errors.

app/services/order_service.ts

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

// Simple message
Monocle.captureMessage("User failed to complete checkout");

// With severity level and context
Monocle.captureMessage("Order processing took too long", {
  level: "warning",
  user: { id: "123" },
  tags: { feature: "checkout" },
  extra: { orderId: "order-456", durationMs: 15000 },
});

Supported levels: debug, info, log, warning, error, fatal.

Tracing Helpers

Creating custom spans

Use record() to wrap a section of code in a span. This is useful when you want to measure the duration of a specific operation that is not automatically instrumented.

app/services/report_service.ts

import { record } from "@monocle.sh/adonisjs-agent/helpers";

const report = await record("report.generate", async (span) => {
  span.setAttributes({ "report.type": "monthly", "report.userId": userId });

  const data = await fetchReportData(userId);
  return generatePdf(data);
});

record() handles both sync and async callbacks, automatically records exceptions, and closes the span when done.

Decorators

The @span() decorator wraps a single method in a span. The @spanAll() decorator wraps every public method in a class.

app/services/order_service.ts

import { inject } from "@adonisjs/core";
import { span, spanAll } from "@monocle.sh/adonisjs-agent/decorators";

// Wrap a single method
export class OrderService {
  @span()
  async findById(id: string) {
    return Order.findOrFail(id);
  }

  @span({ name: "order.create", attributes: { operation: "create" } })
  async create(data: CreateOrderData) {
    return Order.create(data);
  }
}

// Or wrap all methods at once
@spanAll({ prefix: "user" })
export class UserService {
  async findById(id: string) { /* span: user.findById */ }
  async create(data: UserData) { /* span: user.create */ }
}

Other helpers

import {
  getCurrentSpan,
  setAttributes,
  recordEvent,
  injectTraceContext,
  extractTraceContext,
} from "@monocle.sh/adonisjs-agent/helpers";

// Get the current active span
const span = getCurrentSpan();

// Add attributes to the current span
setAttributes({ "order.total": 99.99, "order.currency": "EUR" });

// Record an event on the current span
recordEvent("order.confirmed", { orderId: "123" });

// Distributed tracing: inject context into outgoing headers
const headers = {};
injectTraceContext(headers);

// Distributed tracing: extract context from incoming headers
const context = extractTraceContext(request.headers);

Instrumentations

HTTP

HTTP tracing is configured with the top-level http option. Alongside the standard HTTP instrumentation options, Monocle adds few specific features:

sanitizeUrls to redact sensitive query parameters from URL span attributes
captureBodies to record request and response payloads on spans

Both features are disabled by default. Configure sanitizeUrls to enable URL sanitization. For body capture, set captureBodies.enabled: true, or opt in per side with incoming.request.enabled, incoming.response.enabled, and so on.

config/monocle.ts

export default defineConfig({
  // ...

  // High-level HTTP tracing options.
  http: {
    // Ignore noisy routes before spans are exported.
    ignoredUrls: ["/internal/*", "/api/ping"],

    // Redact sensitive query params in URL span attributes.
    sanitizeUrls: {
      queryParams: ["code", "state", "token", "id_token", "session_state"],
      censor: "REDACTED",
    },

    // Capture request and response payloads on HTTP spans.
    captureBodies: {
      enabled: true,

      // Server-side traffic handled by your Adonis app.
      incoming: {
        request: {
          // Limit the number of bytes stored on the span.
          maxBodySize: 16_384,
        },
        response: {},
      },

      // Client-side traffic instrumented by node:http / node:https.
      outgoing: {
        request: {},
        response: {},
      },

      // Declarative redaction merged with Monocle's built-in safe defaults.
      redact: {
        bodyKeys: ["password", "token", "secret"],
        headers: ["authorization", "cookie"],
        queryParams: ["token"],
        censor: "REDACTED",
      },

      // Final hook to mutate or replace the captured payload.
      transform: (record) => {
        if (!record.http.url?.includes("/oauth/callback")) return;

        record.http.body = { redacted: true };
      },
    },
  },
});

URL sanitization

sanitizeUrls rewrites URL span attributes such as http.url, url.full, http.target, and url.query.

config/monocle.ts

export default defineConfig({
  // ...

  http: {
    sanitizeUrls: {
      queryParams: ["code", "state", "id_token", "session_state"],
    },
  },
});

For example, an OAuth callback like:

/oauth/callback?code=oauth-code&state=oauth-state&id_token=jwt-token

becomes:

/oauth/callback?code=REDACTED&state=REDACTED&id_token=REDACTED

For more control, you can provide a custom sanitize function that takes the full URL object and returns a sanitized string.

config/monocle.ts

export default defineConfig({
  // ...  
  http: {
    sanitizeUrls: {
      sanitize: (url) => {
        // Only keep the pathname for OAuth callbacks
        if (url.pathname === "/oauth/callback") return url.pathname;

        // Otherwise, keep the full URL
        return url.href;
      },
    },
  },
});

Body capture scope

incoming captures traffic handled by your Adonis app:

incoming.request for the HTTP request body sent to your server
incoming.response for the HTTP response body returned by your server

outgoing captures traffic created by Node HTTP clients inside your app:

outgoing.request for the request body your app sends to another service
outgoing.response for the response body returned by that service

captureBodies.outgoing only applies to traffic instrumented by @opentelemetry/instrumentation-http, which means node:http and node:https. It does not cover fetch or undici.

Body capture defaults

captureBodies is opt-in because payload capture can expose sensitive data. When enabled, Monocle:

captures application/json and application/x-www-form-urlencoded by default
stores at most 10_000 bytes per request or response unless you increase maxBodySize
shows captured payloads in the HTTP Body tab of the trace details view

Body capture should be enabled deliberately and reviewed carefully. Payloads can contain credentials or sensitive information. Keep capture scoped to the endpoints you need, prefer the smallest possible maxBodySize, and use redact or transform to remove anything sensitive before it is exported.

Redaction order

captureBodies.redact applies declarative redaction rules first. captureBodies.transform runs after that and lets you mutate or replace the captured payload programmatically. The declarative redact rules extend Monocle’s built-in safe defaults. Common secrets such as password, token, code, access_token, refresh_token, authorization, and many others are redacted automatically even if you do not list them yourself.

Advanced overrides

If you need low-level OpenTelemetry overrides, you can still configure instrumentations["@opentelemetry/instrumentation-http"]. When both are present, the low-level instrumentation config takes priority over the top-level http option.

Mail

If @adonisjs/mail is installed, the agent automatically instruments all emails sent through the mail service. Every email appears as a span in your traces with subject, recipients, and transport info. You can monitor email activity in the dedicated Emails dashboard. To disable:

config/monocle.ts

export default defineConfig({
  // ...
  mail: false,
});

Cache

Install the Bentocache integration explicitly to trace cache operations, including when using @adonisjs/cache. Keep bentocache as a direct application dependency so the integration uses the same instance as your cache service.

Terminal

npm install @monocle.sh/instrumentation-bentocache bentocache

config/monocle.ts

import { defineConfig } from "@monocle.sh/adonisjs-agent";
import { bentocache } from "@monocle.sh/instrumentation-bentocache/integration";
import env from "#start/env";

export default defineConfig({
  apiKey: env.get("MONOCLE_API_KEY"),
  integrations: [bentocache()],
});

The defaults preserve the former cache configuration: keys are captured and sanitized, parent spans are not required, and internal Redis/L2 spans are suppressed. UUIDs, numeric IDs, and hex hashes in keys become *. Pass your previous cache options to bentocache(). Omit the integration or use bentocache({ enabled: false }) to disable it. See the Bentocache guide for customization.

Background Jobs

@adonisjs/queue

If @adonisjs/queue (boringqueue) is installed, the agent instruments job dispatch and execution. Jobs appear in the Jobs dashboard with execution count, error rate, and latency metrics.

config/monocle.ts

export default defineConfig({
  // ...
  queue: {
    // How consumer spans relate to producer spans
    // 'link': consumer span links to producer (default)
    // 'parent': consumer span is a child of the producer span
    executionSpanLinkMode: "link",
  },
});

BullMQ

Install @monocle.sh/instrumentation-bullmq in your BullMQ application, then register bullmq() to trace job dispatch and processing.

Terminal

npm install @monocle.sh/instrumentation-bullmq

config/monocle.ts

import { defineConfig } from "@monocle.sh/adonisjs-agent";
import { bullmq } from "@monocle.sh/instrumentation-bullmq/integration";
import env from "#start/env";

export default defineConfig({
  apiKey: env.get("MONOCLE_API_KEY"),
  integrations: [
    bullmq({ useProducerSpanAsConsumerParent: false }),
  ],
});

Consumer spans link to producer spans by default. Set useProducerSpanAsConsumerParent: true to keep both in the same trace. See the BullMQ guide for all options. Omit bullmq() to disable the Monocle BullMQ integration. Use queue: false to disable the separate Adonis queue integration. The Node auto-instrumentation bundle can still trace underlying Redis operations independently.

Sampling noisy jobs

Use the sampling(ctx) hook to reduce trace volume for high-throughput jobs while keeping failed executions.

config/monocle.ts

import { defineConfig, Sample } from "@monocle.sh/adonisjs-agent";

export default defineConfig({
  // ...
  sampling(ctx) {
    if (ctx.kind === "job" && ctx.name === "SendNewsletterEmail") {
      return Sample.rate(0.01).keepErrors();
    }

    return Sample.default();
  },
});

See Job Sampling for all sampling rules and caveats.

AI SDK

Install the Vercel AI integration and register vercelAi() to trace AI SDK calls, token usage, and costs.

Terminal

npm install @monocle.sh/instrumentation-vercel-ai

config/monocle.ts

import { defineConfig } from "@monocle.sh/adonisjs-agent";
import { vercelAi } from "@monocle.sh/instrumentation-vercel-ai/integration";
import env from "#start/env";

export default defineConfig({
  apiKey: env.get("MONOCLE_API_KEY"),
  integrations: [
    vercelAi({ recordInputs: false, recordOutputs: false }),
  ],
});

Omit vercelAi() to disable this integration. See the Vercel AI guide for supported operations and recording options.

Conversation tracking

Import withConversationId() directly from the integration package to group AI calls in the Conversations tab.

app/services/chat_service.ts

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { withConversationId } from "@monocle.sh/instrumentation-vercel-ai";

export async function reply(conversationId: string, prompt: string) {
  return withConversationId(conversationId, () =>
    generateText({ model: openai("gpt-4o"), prompt }),
  );
}

Mastra

Install the Mastra integration and register mastra() to normalize spans from your Mastra OpenTelemetry bridge. Configure the bridge using the Mastra guide.

Terminal

npm install @monocle.sh/instrumentation-mastra

config/monocle.ts

import { defineConfig } from "@monocle.sh/adonisjs-agent";
import { mastra } from "@monocle.sh/instrumentation-mastra/integration";
import env from "#start/env";

export default defineConfig({
  apiKey: env.get("MONOCLE_API_KEY"),
  integrations: [
    mastra({ recordInputs: false, recordOutputs: false }),
  ],
});

Mastra recording options are independent of vercelAi() options. Set them on both integrations if you use both. Omit mastra() to disable normalization.

CLI Commands

Ace CLI command execution is traced by default. Scaffolding commands (make:*, generate:*) and long-running queue workers are excluded automatically. Command arguments and flags are captured as span attributes (cli.args.*, cli.flags.*).

config/monocle.ts

export default defineConfig({
  // ...
  cli: {
    // Glob patterns to include (all commands by default)
    include: ["migration:*", "db:*"],
    // Glob patterns to exclude (defaults below)
    exclude: ["make:*", "generate:*", "queue:work", "queue:listen"],
  },
});

To disable entirely:

config/monocle.ts

export default defineConfig({
  // ...
  cli: false,
});

CLI tracing requires otel.ts in bin/console.ts.Just like bin/server.ts, your bin/console.ts file must import otel.ts as its very first import for CLI instrumentation to work. The node ace configure command adds this automatically, but if you set up manually or upgraded from an older version, make sure it is there:

bin/console.ts

import '../otel.js' // Must be the first import

import { Kernel } from '@adonisjs/core/ace'
// ...

MCP Server

Install the MCP integration explicitly, then attach it to your server instance. MCP does not need an integrations entry.

Terminal

npm install @monocle.sh/instrumentation-mcp

app/mcp/server.ts

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { instrumentMcpServer } from "@monocle.sh/instrumentation-mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
});

// Instrument before registering tools
instrumentMcpServer(server, {
  // Capture tool arguments in spans (default: false)
  recordInputs: true,
  // Capture tool results in spans (default: false)
  recordOutputs: true,
});

// Register tools, then connect transport as usual
server.tool("ping", async () => ({ content: [{ type: "text", text: "pong" }] }));
await server.connect(new StdioServerTransport());

Multi-Destination OTLP

You can send telemetry to additional OTLP backends alongside Monocle. The Monocle destination is always injected automatically.

config/monocle.ts

import { defineConfig, destinations } from "@monocle.sh/adonisjs-agent";

export default defineConfig({
  // ...

  destinations: [
    destinations.otlp({
      name: "grafana",
      url: "https://otlp-gateway.grafana.net/otlp",
      headers: {
        Authorization: `Basic ${btoa("instance_id:api_key")}`,
      },
    }),
  ],
});

Each destination receives the full telemetry data (traces, metrics, logs).

Disabling Telemetry

If no API key is provided, telemetry is automatically disabled. This is useful for local development.

.env.development

MONOCLE_API_KEY=

Migrating from @adonisjs/otel

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-agent

2. Rename config file

Rename config/otel.ts to config/monocle.ts and replace defineConfig import:

config/monocle.ts

import { defineConfig } from "@adonisjs/otel"; 
import { defineConfig } from "@monocle.sh/adonisjs-agent"; 

3. Update all 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"; 

Why use Monocle’s helpers

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 in the Monocle exception viewer. 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.

​Overview

​Prerequisites

​Installation

​Environment Variables

​Configuration

​Full configuration reference

​Customizing instrumentations

​User Context

​Exception Tracking

​Manual exception capture

​Capture messages

​Tracing Helpers

​Creating custom spans

​Decorators

​Other helpers

​Instrumentations

​HTTP

​URL sanitization

​Body capture scope

​Body capture defaults

​Redaction order

​Advanced overrides

​Mail

​Cache

​Background Jobs

​@adonisjs/queue

​BullMQ

​Sampling noisy jobs

​AI SDK

​Conversation tracking

​Mastra

​CLI Commands

​MCP Server

​Multi-Destination OTLP

​Disabling Telemetry

​Migrating from @adonisjs/otel

​1. Swap the package

​2. Rename config file

​3. Update all imports

​Why use Monocle’s helpers

Overview

Prerequisites

Installation

Environment Variables

Configuration

Full configuration reference

Customizing instrumentations

User Context

Exception Tracking

Manual exception capture

Capture messages

Tracing Helpers

Creating custom spans

Decorators

Other helpers

Instrumentations

HTTP

URL sanitization

Body capture scope

Body capture defaults

Redaction order

Advanced overrides

Mail

Cache

Background Jobs

@adonisjs/queue

BullMQ

Sampling noisy jobs

AI SDK

Conversation tracking

Mastra

CLI Commands

MCP Server

Multi-Destination OTLP

Disabling Telemetry

Migrating from @adonisjs/otel

1. Swap the package

2. Rename config file

3. Update all imports

Why use Monocle’s helpers