跳至主要內容

Arize Exporter

Arize 透過 Phoenix（開源）和 Arize AX（企業版），為 AI 應用程式提供 Observability 平台。Arize Exporter 使用 OpenTelemetry 和 OpenInference 語意慣例傳送 Trace，並相容任何支援 OpenInference 的 OpenTelemetry 平台。

安裝
「安裝」的直接連結

npm install @mastra/arize@latest

設定
「設定」的直接連結

設定 Phoenix
「設定 Phoenix」的直接連結

Phoenix 是開源 Observability 平台，可自行代管或透過 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」的直接連結

Arize AX 是企業級 Observability 平台，為正式環境中的 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
「自訂 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 語意慣例
「OpenInference 語意慣例」的直接連結

此 Exporter 為生成式 AI 應用程式實作 OpenInference 語意慣例，在不同 Observability 平台之間提供標準化的 Trace 結構。

On this page