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：你所屬機構的空間識別碼
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',
  },
})

自訂 metadata

非保留的 span 屬性會序列化至 OpenInference metadata payload，並顯示於 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 語義慣例，在不同可觀測性平台之間提供標準化的 Trace 結構。

相關內容

• Trace 概覽
• Phoenix 文件
• Arize AX 文件
• OpenInference 規格