Mastra

Mastra already creates OpenTelemetry spans through @mastra/otel-bridge. Monocle adds a Mastra observability config helper and a span processor that normalizes Mastra attributes to the fields used by the AI Agents dashboard.

For the full list of required span attributes and what powers the AI dashboard, see the AI Agents feature page.

Installation

npm install @monocle.sh/instrumentation-mastra

Peer dependencies: @mastra/core and @mastra/otel-bridge.

With the AdonisJS agent

Install this integration separately and add mastra() to config/monocle.ts. Installing the package alone does not activate it.

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

export default defineConfig({
  dsn: env.get('MONOCLE_DSN'),
  integrations: [mastra({ recordInputs: false, recordOutputs: false })],
})

The integration normalizes existing spans; configure the Mastra bridge below to emit them. Recording options here are independent of the Vercel AI integration.

Usage with Mastra

Use createMastraObservabilityConfig() in your Mastra config. It creates the Mastra OtelBridge and excludes internal MODEL_STEP and MODEL_CHUNK spans by default because their data is already represented on the model generation span.

For other Node.js applications, add new MastraSpanProcessor() from @monocle.sh/instrumentation-mastra to your existing OpenTelemetry tracer provider. The AdonisJS mastra() integration registers this processor for you.

import { Mastra } from '@mastra/core'
import { Observability, SamplingStrategyType } from '@mastra/observability'
import { createMastraObservabilityConfig } from '@monocle.sh/instrumentation-mastra'

export const mastra = new Mastra({
  agents: {
    // ...
  },
  observability: new Observability({
    configs: {
      monocle: createMastraObservabilityConfig({
        serviceName: 'api',
        sampling: { type: SamplingStrategyType.ALWAYS },
      }),
    },
  }),
})

Normalized attributes

The Mastra processor preserves Mastra spans and adds the attributes Monocle expects:

Model generation metadata is also copied to the parent invoke_agent span when Mastra emits it only on the child model span. This lets the Agents tab show the model, response preview, token usage, and cost on the agent run.

Scorers and evaluations

Mastra scorer events are exported as gen_ai.evaluation.result span events. The event name is a Monocle convention; Monocle reads the standard OpenTelemetry evaluation attributes first:

For richer scorer metadata, use the Monocle evaluation extensions documented on the AI Agents feature page, such as gen_ai.evaluation.scorer.id, gen_ai.evaluation.scorer.version, and gen_ai.evaluation.target.trace_id.