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.

Install

npm install @mastra/arize @mastra/observability

Configure Environment

First, start Phoenix:

Self-Host

Run Phoenix on your own infrastructure, backed by PostgreSQL so traces persist beyond a single process. This is the option to reach for once Phoenix is shared across a team or environment.

The self-hosting guide covers Kubernetes, Helm, Railway, AWS CloudFormation, Google Cloud Run, Azure, and Render, plus authentication and configuration.

Local

uvx arize-phoenix serve

No uv? pip install arize-phoenix && phoenix serve does the same thing. See Terminal setup for customization.

Container

docker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix:latest

Images are published to Docker Hub. See Docker for volumes, PostgreSQL, and other options.

Phoenix serves its UI and OTLP HTTP on port 6006, and OTLP gRPC on port 4317. For a local instance that’s http://localhost:6006 — leave it running while you work.

Then create a .env file that points Mastra at it:

PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces
PHOENIX_API_KEY=your-api-key # Optional, only if auth is enabled
PHOENIX_PROJECT_NAME=mastra-service # Optional

Setup

Initialize the Arize exporter inside your Mastra project.

Zero-config setup (reads from environment variables automatically):

import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { ArizeExporter } from "@mastra/arize";

export const mastra = new Mastra({
  // ... other config (agents, workflows, etc.)
  observability: new Observability({
    configs: {
      arize: {
        serviceName: "mastra-service",
        exporters: [new ArizeExporter()],
      },
    },
  }),
});

Explicit configuration:

import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { ArizeExporter } from "@mastra/arize";

export const mastra = new Mastra({
  // ... other config (agents, workflows, etc.)
  observability: new Observability({
    configs: {
      arize: {
        serviceName: process.env.PHOENIX_PROJECT_NAME || "mastra-service",
        exporters: [
          new ArizeExporter({
            endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
            apiKey: process.env.PHOENIX_API_KEY,
            projectName: process.env.PHOENIX_PROJECT_NAME,
          }),
        ],
      },
    },
  }),
});

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 { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { ArizeExporter } from "@mastra/arize";
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 },
  observability: new Observability({
    configs: {
      arize: {
        serviceName: process.env.PHOENIX_PROJECT_NAME || "mastra-service",
        exporters: [
          new ArizeExporter({
            endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
            apiKey: process.env.PHOENIX_API_KEY,
            projectName: process.env.PHOENIX_PROJECT_NAME,
          }),
        ],
      },
    },
  }),
});

Running Your Application

To test your application with Phoenix tracing:

# Start the Mastra dev server
mastra dev

## or, build and run the production server with instrumentation enabled
# npm run build
# node --import=./.mastra/output/instrumentation.mjs .mastra/output/index.mjs

This will:

1. Initialize the tracing SDK with your observability configuration
2. Start the Mastra playground at http://localhost:4111
3. 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 Arize exporter docs
• Mastra CLI Documentation