Mastra Tracing

Instrument agent applications built with Mastra

Mastra is an agentic framework that simplifies building complex AI applications with multi-agent workflows, tool integrations, and memory management.

Launch Phoenix

Phoenix Cloud

1. Sign up for an Arize Phoenix account at https://app.phoenix.arize.com/login

2. Grab your API key from the Keys option on the left bar.

3. In your code, configure environment variables for your endpoint and API key:

# .env, or shell environment

# Add Phoenix API Key for tracing
PHOENIX_API_KEY="ADD YOUR PHOENIX API KEY"
# And Collector Endpoint for Phoenix Cloud
PHOENIX_COLLECTOR_ENDPOINT="ADD YOUR PHOENIX HOSTNAME"

Self-Hosted Phoenix

1. Run Phoenix using Docker, local terminal, Kubernetes etc. For more information, see self-hosting.

2. In your code, configure environment variables for your endpoint and API key:

# .env, or shell environment
​
# Collector Endpoint for your self hosted Phoenix, like localhost
PHOENIX_COLLECTOR_ENDPOINT="http://localhost:6006"
# (optional) If authentication enabled, add Phoenix API Key for tracing
PHOENIX_API_KEY="ADD YOUR API KEY"

Install

npm install @arizeai/openinference-mastra@^2.2.0 @mastra/core
npm install -D mastra 

Setup

Initialize OpenTelemetry tracing for your Mastra application:

import { Mastra } from '@mastra/core/mastra';
import {
  OpenInferenceOTLPTraceExporter,
  isOpenInferenceSpan,
} from "@arizeai/openinference-mastra";

export const mastra = new Mastra({
  // ... other config (agents, workflows, etc.)
  telemetry: {
    serviceName: "my-mastra-app",
    enabled: true,
    export: {
      type: "custom",
      tracerName: "my-mastra-app",
      exporter: new OpenInferenceOTLPTraceExporter({
        url: process.env.PHOENIX_COLLECTOR_ENDPOINT + "/v1/traces",
        headers: {
          Authorization: `Bearer ${process.env.PHOENIX_API_KEY}`,
        },
        spanFilter: isOpenInferenceSpan,
      }),
    },
  },
});

ℹ️ Running with Mastra Dev Server

Phoenix tracing is enabled only when running your app with the Mastra dev server:

• Use mastra dev to send traces to Phoenix.

• Running scripts directly (e.g., with node or tsx) will not enable tracing.

Create Agents and Tools

From here you can use Mastra as normal. Create agents with tools and run them:

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

// Create a simple weather tool
const weatherTool = {
  name: "weatherTool",
  description: "Get current weather for a location",
  parameters: z.object({
    location: z.string().describe("The city and country"),
  }),
  execute: async ({ location }) => {
    // Simulate weather API call
    return {
      location,
      temperature: "22°C",
      condition: "Sunny",
      humidity: "60%"
    };
  },
};

// Create an agent
const weatherAgent = new Agent({
  name: "Weather Assistant",
  instructions: "You help users get weather information. Use the weather tool to get current conditions.",
  model: openai("gpt-4o-mini"),
  tools: { weatherTool },
});

// Register the agent with Mastra instance
const mastra = new Mastra({
  agents: { weatherAgent },
  telemetry: {
    serviceName: "mastra-weather-agent",
    enabled: true,
    export: {
      type: "custom",
      tracerName: "mastra-weather-agent",
      exporter: new OpenInferenceOTLPTraceExporter({
        url: process.env.PHOENIX_COLLECTOR_ENDPOINT + "/v1/traces",
        headers: {
          Authorization: `Bearer ${process.env.PHOENIX_API_KEY}`,
        },
        spanFilter: isOpenInferenceSpan,
      }),
    },
  },
});

Running Your Application

To start your application with Phoenix tracing:

# Start the Mastra dev server (required for tracing)
mastra dev

This will:

1. Generate OpenTelemetry instrumentation files in .mastra/output/

2. Initialize the tracing SDK with your telemetry configuration

3. Start the Mastra playground at http://localhost:4111

4. Enable trace export to Phoenix at http://localhost:6006

Interact with your agents:

• Via Playground: Navigate to http://localhost:4111/playground to chat with agents

• Via API: Make requests to the generated API endpoints

• Programmatically: Create test scripts that run within the mastra dev environment

Observe

Now that you have tracing setup, all agent runs, tool calls, and model interactions will be streamed to your running Phoenix for observability and evaluation.

Resources

• Working example

• Mastra CLI Documentation