Mastra Observability & Monitoring with OpenTelemetry

What is Mastra Observability?

Mastra observability lets you instrument your AI applications using OpenTelemetry and export traces to SigNoz. This guide walks you through setting up Mastra monitoring so you get real-time visibility into model performance, latency, error rates, and usage trends across your Mastra applications.

With full Mastra observability in SigNoz, you can correlate traces, logs, and metrics across AI workflows, set alerts on error rates and latency, and continuously improve the reliability of your Mastra applications.

Prerequisites

A SigNoz Cloud account with an active ingestion key
Internet access to send telemetry data to SigNoz Cloud
Node.js (v20.0 or higher)
An API key from a supported Model Provider

Setting Up Mastra Observability with OpenTelemetry

You can get the full Mastra installation instructions.

Step 1: Start the CLI Wizard

Run the following command to start the interactive setup:

npx create-mastra@latest

Step 2: Add Your API key

Add your API key to the .env file:

OPENAI_API_KEY=<your-api-key>

This example uses OpenAI. Each LLM provider uses a unique name. See Model Capabilities for more information.

Setup an Agent

Step 1: Create an agent in your project.

For example, create a file src/mastra/agents/chefAgent.ts:

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";

export const chefAgent = new Agent({
  name: "chef-agent",
  instructions:
    "You are Michel, a practical and experienced home chef" +
    "You help people cook with whatever ingredients they have available.",
  model: openai("gpt-4o-mini"),
});

Step 2: Register the Agent with Mastra

In your src/mastra/index.ts file, register the agent with telemetry enabled:

import { Mastra } from "@mastra/core";
import { chefAgent } from "./agents/chefAgent";
import { OtelExporter } from "@mastra/otel-exporter";


export const mastra = new Mastra({
  agents: { chefAgent },
  observability: {
    configs: {
      otel: {
        serviceName: '<service-name>',
        exporters: [
          new OtelExporter({
            provider: {
              signoz: {
                apiKey: process.env.SIGNOZ_INGESTION_KEY,
                region: 'us', // 'us' | 'eu' | 'in',
              }
            },
          })
        ],
      },
    },
  },
});

<service_name> is the name of your service
SIGNOZ_INGESTION_KEY → Your SigNoz ingestion key. Set the value as an environment variable.
region → appropriate region

Step 3: Run Mastra Dev Server and Interact with Agent

npm run dev

You should see some output similar to this:

Execution Output — *Output when running the Mastra Dev Server*

Visit the playground url, and start chatting with the registered agent. All your interactions should be traced and sent to SigNoz under the traces tab.

View Mastra Traces in SigNoz

Once configured, your Mastra application automatically emits traces.

Traces are available in SigNoz Cloud under the Traces tab:

When you click on a trace in SigNoz, you'll see a detailed view of the trace, including all associated spans, along with their events and attributes.

Mastra Observability Dashboard

You can also check out our Mastra Dashboard which provides specialized visualizations for Mastra monitoring in your applications. The dashboard includes pre-built charts specifically tailored for LLM usage, along with import instructions to get started quickly.