Get started with Mastra Observability

You've got peanut butter and jelly, cookies and milk, and now Mastra and Mastra Observability! 😏 It's the natural pairing for agents that need traces, metrics, and evals, so you can keep improving them after they ship.

Mastra Observability is a hosted platform that connects directly to your Mastra framework project. It gives you and your team one place to see what your agents are doing in production, investigate problems, and run the eval loop that makes them better, so you don't need a separate observability/evals platform.

Here's how it works:

Connect your project

Connect your project and Mastra automatically traces your agent runs, so you can understand how users interact with your product and investigate when something goes wrong.

import { Mastra } from '@mastra/core/mastra';
import {
  Observability,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability';
 
export const mastra = new Mastra({
  // Automatically trace every agent, workflow, and tool
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        // Mastra batches traces and sends them to the platform
        // asynchronously in the background.
        exporters: [new MastraPlatformExporter()],
        // Redact sensitive fields before exporting traces
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
});

note

First, create a Mastra account, then follow the getting started guide to connect your Mastra project.

Understand every agent run

Search and filter traces to find the runs that matter, then inspect model and tool calls to see exactly where time and tokens were spent, and what they cost.

Thread view (pictured above) puts each run in the context of the full conversation. You and your non-technical teammates can start with the messages and drill into the steps behind them when something looks off - no need to decode a raw span tree first.

Monitor performance, cost, and correctness

Run online scorers on a sample of your traces to track correctness automatically, then watch the trends over time on a dashboard alongside the performance and cost metrics you already care about.

Build an eval loop

Invite your team to review conversations, annotate traces, and curate datasets for your eval loop.

Run an experiment against your dataset and compare versions of your agent on quality, cost, and latency.

Here I’m comparing results to see if I can downgrade to nano and save on cost without degrading performance (spoiler: I can’t!)

Use AI to improve agents

As agent harnesses take on bigger jobs and rack up longer runs, there’s a lot more trace data to make sense of.

Mastra’s query traces CLI gives your coding agent a way to investigate slow, expensive, or failed runs and help fix the underlying issues.

Trace Intelligence (private beta) surfaces recurring failure patterns, helping you find the signal in the noise. It groups traces by goals, behavior, sentiment, and outcomes so you can prioritize fixes and select examples for evals.

note

You can request access to Trace Intelligence.

Catch regressions in CI with Gates and Verdicts

Evals don't have to live only in a dashboard. Run them in code to catch regressions in CI/CD before you ship. Gates and Verdicts turn behavior checks and scorer thresholds into a pass/fail verdict your test suite can assert on.

import { runEvals } from '@mastra/core/evals';
 
try {
  // Check your agent against your quality requirements
  const result = await runEvals({
    target: refundPolicyAgent,
    data,
    scorers: [{ scorer: refundCorrectnessScorer, threshold: 1 }],
  });
 
  console.log('Refund check:', result.verdict);
  if (result.verdict !== 'passed') {
    process.exitCode = 1;
  }
} catch (error) {
  console.error('Refund check could not complete:', error);
  process.exitCode = 1;
}

Optionally turn this into a GitHub Action, so every pull request runs your evals automatically and shows the verdict as a check, helping you catch regressions before you merge.

100k events a month, for free

We want you to be able to see what your agents are doing in production from day one, so we're giving you 100k observability events free every month, with 15 days of retention (no credit card required). Need more? Additional usage is $10 per 100k events.

The Teams plan is $250/month and includes 1m events per month, six months of retention, multiple teams, SSO, and SOC 2 documentation. Additional usage costs $8 per 100k events.

note

Get started with Mastra Observability or compare plans.

If you’re moving from another platform, follow our trace import guide or get in touch for help bringing your traces and datasets to Mastra.