跳到主要内容

Arize exporter

Arize 通过开源的 Phoenix 和企业级 Arize AX 为 AI 应用提供可观测性平台。Arize exporter 使用 OpenTelemetry 和 OpenInference 语义约定发送 Trace，并与任何支持 OpenInference 的 OpenTelemetry 平台兼容。

安装
安装的直接链接

npm install @mastra/arize@latest

配置
配置的直接链接

Phoenix 设置
Phoenix 设置的直接链接

Phoenix 是一个开源可观测性平台，可以自托管，也可以通过 Phoenix Cloud 使用。

前提条件
前提条件的直接链接

  1. Phoenix 实例：使用 Docker 部署，或注册 Phoenix Cloud
  2. Endpoint：Phoenix endpoint URL（以 /v1/traces 结尾）
  3. API key：未认证实例可选，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 是一个企业级可观测性平台，为生产 AI 系统提供高级功能。

前提条件
前提条件的直接链接

  1. Arize AX 账户：在 app.arize.com 注册
  2. Space ID：组织的 space 标识符
  3. API key：在 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)
})

Resource 属性
Resource 属性的直接链接

向所有导出的 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 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 语义约定，可在不同可观测性平台间提供标准化 Trace 结构。

On this page