Migrate to AdonisJS agent 2.0.0

Version 2.0.0 stops bundling Mastra, Vercel AI, BullMQ, Bentocache, and MCP integrations. Install and configure only the ones you use.

Node auto-instrumentation and built-in Adonis mail, queue, and CLI tracing stay included. Keep your mail, queue, cli, endpoint, API key, destinations, and sampling options.

1. Install the integrations you use

Upgrade the agent, then install the integrations your application needs. Keep their host libraries as direct application dependencies.

npm install @monocle.sh/adonisjs-agent@^2.0.0

npm install @monocle.sh/instrumentation-bullmq

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

npm install @monocle.sh/instrumentation-mastra

npm install @monocle.sh/instrumentation-bentocache bentocache

npm install @monocle.sh/instrumentation-mcp

2. Register integrations

Replace the top-level ai, mastra, bullmq, and cache options with entries in integrations. Keep only the imports and entries you use; omit an integration to disable it. Installing a package alone no longer activates it.

 import { defineConfig } from "@monocle.sh/adonisjs-agent";
+import { bullmq } from "@monocle.sh/instrumentation-bullmq/integration";
+import { vercelAi } from "@monocle.sh/instrumentation-vercel-ai/integration";
+import { mastra } from "@monocle.sh/instrumentation-mastra/integration";
+import { bentocache } from "@monocle.sh/instrumentation-bentocache/integration";
 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"),
-  bullmq: { useProducerSpanAsConsumerParent: false },
-  ai: { recordInputs: false, recordOutputs: false },
-  mastra: {},
-  cache: { includeKeys: false },
+  integrations: [
+    bullmq({ useProducerSpanAsConsumerParent: false }),
+    vercelAi({ recordInputs: false, recordOutputs: false }),
+    mastra({ recordInputs: false, recordOutputs: false }),
+    bentocache({ includeKeys: false }),
+  ],
 });

• AI recording: Mastra no longer inherits ai.recordInputs or ai.recordOutputs. Set them on both mastra() and vercelAi() to preserve disabled recording, as above. Keep your Mastra OpenTelemetry bridge.
• BullMQ: The integration inherits the agent's sampling callback unless you override it in bullmq(). Omitting or disabling it does not bypass generic job sampling. Keep useProducerSpanAsConsumerParent for trace linking; executionSpanLinkMode is an Adonis queue option.
• Cache: Move existing cache options into bentocache(). Keep bentocache as a direct dependency even when using @adonisjs/cache. Cache defaults and key sanitization stay the same.

Built-in mail, queue, and cli options stay at the top level. Use false or { enabled: false } to disable them. Underlying Node instrumentations, such as Redis tracing, can still emit spans independently.

3. Update helper imports

Replace the removed /ai and /mcp imports. The helpers keep their existing usage.

-import { withConversationId, getConversationId } from "@monocle.sh/adonisjs-agent/ai";
+import { withConversationId, getConversationId } from "@monocle.sh/instrumentation-vercel-ai";
-import { instrumentMcpServer } from "@monocle.sh/adonisjs-agent/mcp";
+import { instrumentMcpServer } from "@monocle.sh/instrumentation-mcp";
-import type { InstrumentMcpServerOptions } from "@monocle.sh/adonisjs-agent/mcp";
+import type { InstrumentMcpServerOptions } from "@monocle.sh/instrumentation-mcp";

MCP stays attached to a server instance: call instrumentMcpServer() before connecting a transport, without adding it to integrations.

4. Verify the upgrade

1. Run your application's type checker to catch old options and imports.
2. Keep import '../otel.js' first in bin/server.ts and bin/console.ts so instrumentation hooks load before application libraries.
3. Restart the application and workers. Exercise each enabled integration and confirm its spans appear in Monocle Cloud or Studio, with the expected input/output recording settings.
4. Remove unused integration packages from your application's dependencies.

If an /integration export is missing, upgrade the agent and integration packages together and reinstall dependencies. If initialization fails, the error identifies the integration: check its configuration and compatible host library, or remove the entry if unused.

Service version is detected automatically

The agent no longer requires APP_NAME or APP_VERSION. The configurator generates only APP_ENV and MONOCLE_DSN and their validators. The agent detects the version in this order:

1. serviceVersion in config/monocle.ts
2. MONOCLE_VERSION
3. APP_VERSION
4. The revision exposed by Vercel, Render, Railway, Heroku, Coolify, Dokku, or Cloud Run
5. The commit SHA exposed by a supported CI provider, such as GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines, or Buildkite
6. The current commit of the local .git directory

The agent skips empty values and the placeholders 0.0.0, 0.0.1, 1.0.0, unknown, dev, and latest. To pin a version, set APP_VERSION or MONOCLE_VERSION to a real value. Neither needs a config line.

Existing apps need no change. The old serviceVersion: env.get('APP_VERSION') line and its validator still work. An APP_VERSION=0.0.1 placeholder is skipped, so detection takes over.

If you remove APP_VERSION from .env, also remove its serviceVersion: env.get('APP_VERSION') config line and validator from start/env.ts.

With a DSN, the collector uses the name of the service attached to the DSN. In Studio or without a DSN, the name comes from serviceName, then OTEL_SERVICE_NAME, then APP_NAME, then the app's package.json name without its npm scope. If no name is available, it uses unknown_service.