> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```bash theme={null}
npm install @mastra/arize @mastra/observability
```
## Configure Environment
First, start Phoenix:
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](/docs/phoenix/self-hosting) covers [Kubernetes](/docs/phoenix/self-hosting/deployment-options/kubernetes), [Helm](/docs/phoenix/self-hosting/deployment-options/kubernetes-helm), [Railway](/docs/phoenix/self-hosting/deployment-options/railway), [AWS CloudFormation](/docs/phoenix/self-hosting/deployment-options/aws-with-cloudformation), [Google Cloud Run](/docs/phoenix/self-hosting/deployment-options/google-cloud-run), [Azure](/docs/phoenix/self-hosting/deployment-options/azure), and [Render](/docs/phoenix/self-hosting/deployment-options/render), plus authentication and configuration.
```bash theme={null}
uvx arize-phoenix serve
```
No [uv](https://docs.astral.sh/uv/)? `pip install arize-phoenix && phoenix serve` does the same thing. See [Terminal setup](/docs/phoenix/environments#terminal) for customization.
```bash theme={null}
docker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix:latest
```
Images are published to [Docker Hub](https://hub.docker.com/r/arizephoenix/phoenix). See [Docker](/docs/phoenix/self-hosting/deployment-options/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](http://localhost:6006) — leave it running while you work.
Then create a `.env` file that points Mastra at it:
```bash theme={null}
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):
```typescript theme={null}
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:**
```typescript theme={null}
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:
```typescript theme={null}
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:**
```bash theme={null}
# 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](https://github.com/Arize-ai/phoenix/tree/main/tutorials/agents/mastra/example-agent)
* [Mastra Arize exporter docs](https://mastra.ai/docs/observability/tracing/exporters/arize)
* [Mastra CLI Documentation](https://mastra.ai/docs/getting-started/installation)