Arize

Arize AI provides observability and evaluation for AI applications through Arize Phoenix and Arize AX. Use Phoenix for a local or self-hosted open-source workflow, and use Arize AX for managed cloud or enterprise self-hosted production observability. The Arize exporter sends traces using OpenTelemetry and OpenInference semantic conventions, compatible with any OpenTelemetry platform that supports OpenInference.

For workflows that use traces to improve quality, see Arize's agent evaluation guide and LLM evaluation guide.

Installation

npm

npm install @mastra/arize@latest

pnpm

pnpm add @mastra/arize@latest

Yarn

yarn add @mastra/arize@latest

Bun

bun add @mastra/arize@latest

Configuration

Phoenix Setup

Phoenix is an open-source observability platform that can run locally or be self-hosted.

Prerequisites

1. Phoenix Instance: Run Phoenix locally with Docker or connect to your self-hosted deployment
2. Endpoint: Your Phoenix endpoint URL (ends in /v1/traces)
3. API Key: Optional for unauthenticated instances, required for authenticated deployments
4. Environment Variables: Set your configuration

.env

# Required
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces  # Or your self-hosted Phoenix URL

# Optional
PHOENIX_API_KEY=your-api-key  # For authenticated Phoenix instances
PHOENIX_PROJECT_NAME=mastra-service  # Defaults to 'mastra-service'

Zero-Config Setup

With environment variables set, use the exporter with no configuration:

src/mastra/index.ts

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      arize: {
        serviceName: 'mastra-service',
        exporters: [new ArizeExporter()],
      },
    },
  }),
})

Explicit Configuration

You can also pass credentials directly (takes precedence over environment variables):

src/mastra/index.ts

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

export const mastra = new Mastra({
  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,
          }),
        ],
      },
    },
  }),
})

Quickstart with Docker

Test locally with an in-memory Phoenix instance:

docker run --pull=always -d --name arize-phoenix -p 6006:6006 \
  -e PHOENIX_SQL_DATABASE_URL="sqlite:///:memory:" \
  arizephoenix/phoenix:latest

Set PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces and run your Mastra agent to see traces at localhost:6006.

Arize AX Setup

Arize AX is a managed cloud and enterprise self-hosted observability platform with advanced features for production AI systems.

Prerequisites

1. Arize AX Account: Sign up at app.arize.com
2. Space ID: Your organization's space identifier
3. API Key: Generate in Arize AX settings
4. Environment Variables: Set your credentials

.env

# Required
ARIZE_SPACE_ID=your-space-id
ARIZE_API_KEY=your-api-key

# Optional
ARIZE_PROJECT_NAME=mastra-service

Zero-Config Setup

With environment variables set, use the exporter with no configuration:

src/mastra/index.ts

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      arize: {
        serviceName: 'mastra-service',
        exporters: [new ArizeExporter()],
      },
    },
  }),
})

Explicit Configuration

You can also pass credentials directly (takes precedence over environment variables):

src/mastra/index.ts

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      arize: {
        serviceName: process.env.ARIZE_PROJECT_NAME || 'mastra-service',
        exporters: [
          new ArizeExporter({
            apiKey: process.env.ARIZE_API_KEY!,
            spaceId: process.env.ARIZE_SPACE_ID!,
            projectName: process.env.ARIZE_PROJECT_NAME,
          }),
        ],
      },
    },
  }),
})

Configuration options

The Arize exporter supports advanced configuration for fine-tuning OpenTelemetry behavior:

Complete Configuration

new ArizeExporter({
  // Phoenix Configuration
  endpoint: 'https://your-collector.example.com/v1/traces', // Required for Phoenix

  // Arize AX Configuration
  spaceId: 'your-space-id', // Required for Arize AX

  // Shared Configuration
  apiKey: 'your-api-key', // Required for authenticated endpoints
  projectName: 'mastra-service', // Optional project name

  // Optional OTLP settings
  headers: {
    'x-custom-header': 'value', // Additional headers for OTLP requests
  },

  // Debug and performance tuning
  logLevel: 'debug', // Logging: debug | info | warn | error
  batchSize: 512, // Batch size before exporting spans
  timeout: 30000, // Timeout in ms before exporting spans

  // Custom resource attributes
  resourceAttributes: {
    'deployment.environment': process.env.NODE_ENV,
    'service.version': process.env.APP_VERSION,
  },
})

Batch Processing Options

Control how traces are batched and exported:

new ArizeExporter({
  endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
  apiKey: process.env.PHOENIX_API_KEY,

  // Batch processing configuration
  batchSize: 512, // Number of spans to batch (default: 512)
  timeout: 30000, // Max time in ms to wait before export (default: 30000)
})

Resource Attributes

Add custom attributes to all exported spans:

new ArizeExporter({
  endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
  resourceAttributes: {
    'deployment.environment': process.env.NODE_ENV,
    'service.namespace': 'production',
    'service.instance.id': process.env.HOSTNAME,
    'custom.attribute': 'value',
  },
})

Custom metadata

Non-reserved span attributes are serialized into the OpenInference metadata payload and surface in Arize/Phoenix. You can add them via tracingOptions.metadata:

await agent.generate(input, {
  tracingOptions: {
    metadata: {
      companyId: 'acme-co',
      tier: 'enterprise',
    },
  },
})

Reserved fields such as input, output, sessionId, thread/user IDs, and OpenInference IDs are excluded automatically.

OpenInference semantic conventions

This exporter implements the OpenInference Semantic Conventions for generative AI applications, providing standardized trace structure across different observability platforms.

Related

• Tracing Overview
• Phoenix Documentation
• Arize AX Documentation
• OpenInference Specification