Mastra Tracing - Phoenix

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:

uvx arize-phoenix serve

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

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/tracesPHOENIX_ENDPOINT=http://localhost:6006 # Only if you also read data back via the API clientsPHOENIX_API_KEY=your-api-key # Optional, only if auth is enabledPHOENIX_PROJECT_NAME=mastra-service # Optional

PHOENIX_COLLECTOR_ENDPOINT is the exact URL traces are sent to. ArizeExporter POSTs to it verbatim, so it carries the OTLP /v1/traces path and the setup below passes it straight through.

Setup#

Initialize the Arize exporter inside your Mastra project:

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,          }),        ],      },    },  }),});

Warning

The /v1/traces path matters. ArizeExporter — unlike Phoenix’s own SDKs — does not append the OTLP path itself: handed a bare server URL such as http://localhost:6006, every span goes to the wrong path, Mastra’s batching exporter swallows the delivery error, and traces simply never appear. Phoenix’s own tools accept the suffixed value, stripping the path when they need a base URL (see environment variables).

One exception to keep in mind: arize-phoenix-otel (Python) defaults to OTLP/gRPC for self-hosted servers and does not strip the path, so if a Python service reads this same variable give it the bare server URL instead.

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 toolconst 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 agentconst 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 instanceconst 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 servermastra 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:

Initialize the tracing SDK with your observability configuration
Start the Mastra playground at http://localhost:4111
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.