Arize exporter

Arize は、Phoenix（オープンソース）と Arize AX（エンタープライズ）を通じて、AI アプリケーション向けのオブザーバビリティプラットフォームを提供します。Arize exporter は、OpenTelemetry と OpenInference のセマンティック規約を使用して Trace を送信します。OpenInference に対応するあらゆる OpenTelemetry プラットフォームと互換性があります。

インストール

npm

npm install @mastra/arize@latest

pnpm

pnpm add @mastra/arize@latest

Yarn

yarn add @mastra/arize@latest

Bun

bun add @mastra/arize@latest

設定

Phoenix のセットアップ

Phoenix は、セルフホストまたは Phoenix Cloud で利用できるオープンソースのオブザーバビリティプラットフォームです。

前提条件

1. Phoenix インスタンス：Docker を使用してデプロイするか、Phoenix Cloud に登録する
2. エンドポイント：Phoenix エンドポイントの URL（/v1/traces で終わるもの）
3. API キー：認証なしのインスタンスではオプション、Phoenix Cloud では必須
4. 環境変数：設定を指定する

.env

# Required
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces  # Or your Phoenix Cloud URL

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

設定不要のセットアップ

環境変数を設定したら、設定を渡さずに exporter を使用できます。

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

明示的な設定

認証情報を直接渡すこともできます。この値は環境変数より優先されます。

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

Docker を使用したクイックスタート

インメモリの Phoenix インスタンスを使用してローカルでテストします。

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

PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces を設定して Mastra Agent を実行すると、localhost:6006 で Trace を確認できます。

Arize AX のセットアップ

Arize AX は、本番環境の AI システム向けに高度な機能を備えたエンタープライズオブザーバビリティプラットフォームです。

前提条件

1. Arize AX アカウント：app.arize.com で登録する
2. Space ID：組織の space 識別子
3. API キー：Arize AX の設定で生成する
4. 環境変数：認証情報を設定する

.env

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

# Optional
ARIZE_PROJECT_NAME=mastra-service

設定不要のセットアップ

環境変数を設定したら、設定を渡さずに exporter を使用できます。

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

明示的な設定

認証情報を直接渡すこともできます。この値は環境変数より優先されます。

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

設定オプション

Arize exporter は、OpenTelemetry の動作を細かく調整するための高度な設定に対応しています。

完全な設定

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

バッチ処理のオプション

Trace をバッチ化してエクスポートする方法を制御します。

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

リソース属性

エクスポートするすべての span にカスタム属性を追加します。

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',
  },
})

カスタムメタデータ

予約されていない span 属性は OpenInference の metadata ペイロードへシリアライズされ、Arize/Phoenix に表示されます。tracingOptions.metadata を使用して追加できます。

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

input、output、sessionId、thread/user ID、OpenInference ID などの予約済みフィールドは自動的に除外されます。

OpenInference のセマンティック規約

この exporter は生成 AI アプリケーション向けの OpenInference Semantic Conventions を実装し、さまざまなオブザーバビリティプラットフォームで標準化された Trace 構造を提供します。

関連項目

• トレーシングの概要
• Phoenix ドキュメント
• Arize AX ドキュメント
• OpenInference 仕様