> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140-claude-llms-txt-2026-08-12.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_ENDPOINT=http://localhost:6006 # Only if you also read data back via the API clients
PHOENIX_API_KEY=your-api-key # Optional, only if auth is enabled
PHOENIX_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:
```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,
}),
],
},
},
}),
});
```
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](/docs/phoenix/environments)).
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:
```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)