Mastra

This guide explains how to:

Install and register the Mastra integration
Connect Mastra’s OpenTelemetry bridge
Monitor agent runs, LLM calls, token usage, and evaluations

Overview

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

Terminal

npm install @monocle.sh/instrumentation-mastra

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

With the AdonisJS agent

Registration through integrations requires AdonisJS agent 2.x. See the migration guide when upgrading from 1.x.

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

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 })],
});

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.

mastra/index.ts

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:

Mastra attribute	Monocle attribute
`gen_ai.provider.name`	`gen_ai.system`
`gen_ai.output.messages`	`gen_ai.response.text`
`gen_ai.tool.call.arguments`	`gen_ai.tool.input`
`gen_ai.tool.call.result`	`gen_ai.tool.output`
`gen_ai.agent.name`	`gen_ai.function_id`
`gen_ai.usage.cached_input_tokens`	`gen_ai.usage.input_tokens.cached`
`gen_ai.usage.reasoning_tokens`	`gen_ai.usage.output_tokens.reasoning`

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:

Attribute	Description
`gen_ai.evaluation.name`	Scorer name
`gen_ai.evaluation.score.value`	Numeric score value
`gen_ai.evaluation.score.label`	Optional score label
`gen_ai.evaluation.explanation`	Explanation for the score

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.

Getting Started

Monocle Studio

Frameworks

Features

Integrations

Migrations

Other

Overview

Installation

With the AdonisJS agent

Usage with Mastra

Normalized attributes

Scorers and evaluations

​Overview

​Installation

​With the AdonisJS agent

​Usage with Mastra

​Normalized attributes

​Scorers and evaluations

Overview

Installation

With the AdonisJS agent

Usage with Mastra

Normalized attributes

Scorers and evaluations