Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.monocle.sh/llms.txt

Use this file to discover all available pages before exploring further.

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 attributeMonocle attribute
gen_ai.provider.namegen_ai.system
gen_ai.output.messagesgen_ai.response.text
gen_ai.tool.call.argumentsgen_ai.tool.input
gen_ai.tool.call.resultgen_ai.tool.output
gen_ai.agent.namegen_ai.function_id
gen_ai.usage.cached_input_tokensgen_ai.usage.input_tokens.cached
gen_ai.usage.reasoning_tokensgen_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:
AttributeDescription
gen_ai.evaluation.nameScorer name
gen_ai.evaluation.score.valueNumeric score value
gen_ai.evaluation.score.labelOptional score label
gen_ai.evaluation.explanationExplanation 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.