Skip to main content
This guide covers how to:
  • Install and register the integrations your application uses
  • Preserve recording settings and update helper imports
  • Verify telemetry after upgrading

​
Overview

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.
Terminal

​
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.
config/monocle.ts
  • 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.
app/services/telemetry.ts
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.