> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140-claude-graphql-project-auth-check-eta8st.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

Create a `.env` file that points Mastra to your Phoenix instance:

<Tabs>
  <Tab title="Phoenix Cloud">
    1. Sign up for an Arize Phoenix account at [https://app.phoenix.arize.com/login](https://app.phoenix.arize.com/login)
    2. Grab your API key from the Keys option on the left bar.
    3. Find your hostname under **Settings > Hostname**.

    ```bash theme={null}
    PHOENIX_COLLECTOR_ENDPOINT=https://app.phoenix.arize.com/s/<your-space-name>/v1/traces
    PHOENIX_API_KEY=your-api-key
    PHOENIX_PROJECT_NAME=mastra-service # Optional
    ```
  </Tab>

  <Tab title="Self-hosted Phoenix">
    1. Run Phoenix using Docker, local terminal, Kubernetes etc. For more information, see [self-hosting](/docs/phoenix/self-hosting).

    ```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
    ```
  </Tab>
</Tabs>

## 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.

<Frame>
  <img src="https://storage.googleapis.com/arize-phoenix-assets/assets/images/mastra-traces.png" alt="Mastra traces in Phoenix" />
</Frame>

## 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)