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

# Mastra

> Instrument Mastra agents and workflows for AI observability

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](/features/ai-agents).

## Installation

```bash theme={"theme":"vesper"}
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.

```typescript title="mastra/index.ts" theme={"theme":"vesper"}
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](/features/ai-agents#evaluation-result-attributes), such as `gen_ai.evaluation.scorer.id`, `gen_ai.evaluation.scorer.version`, and `gen_ai.evaluation.target.trace_id`.