Mastra

This guide covers how to instrument Mastra for monitoring agent runs, LLM calls, token usage, tool calls, and costs. 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.

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. When using @monocle.sh/adonisjs-agent, the MastraSpanProcessor is registered automatically when this package is installed. In other Node.js applications, add new MastraSpanProcessor() to your OpenTelemetry tracer provider so Mastra spans are normalized for Monocle.

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

Other

Installation

Usage with Mastra

Normalized attributes

Scorers and evaluations

​Installation

​Usage with Mastra

​Normalized attributes

​Scorers and evaluations

Installation

Usage with Mastra

Normalized attributes

Scorers and evaluations