Arize 导出器

🌐 Arize Exporter

Arize 通过 Phoenix（开源）和 Arize AX（企业版）为 AI 应用提供可观测性平台。Arize 导出器使用 OpenTelemetry 和 OpenInference 语义规范发送追踪数据，兼容任何支持 OpenInference 的 OpenTelemetry 平台。

安装

🌐 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 是一个开源的可观察性平台，可以自建部署，也可以通过 Phoenix Cloud 使用。

🌐 Phoenix is an open-source observability platform that can be self-hosted or used via Phoenix Cloud.

先决条件

🌐 Prerequisites

1. Phoenix 实例：使用 Docker 部署或在 Phoenix Cloud 注册
2. 端点：你的 Phoenix 端点 URL（以 /v1/traces 结尾）
3. API密钥：未认证实例可选，Phoenix Cloud 必填
4. 环境变量：设置你的配置

.env

# Required
PHOENIX_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'

零配置设置

🌐 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_ENDPOINT!,
            apiKey: process.env.PHOENIX_API_KEY,
            projectName: process.env.PHOENIX_PROJECT_NAME,
          }),
        ],
      },
    },
  }),
});

info

Docker 快速入门

使用内存中的 Phoenix 实例在本地进行测试：

🌐 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

设置 PHOENIX_ENDPOINT=http://localhost:6006/v1/traces 并运行你的 Mastra 代理，以在 localhost:6006 查看跟踪。

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

Arize AX 设置

🌐 Arize AX Setup

Arize AX 是一个面向企业的可观察性平台，具有用于生产 AI 系统的高级功能。

🌐 Arize AX is an enterprise observability platform with advanced features for production AI systems.

先决条件

🌐 Prerequisites

1. Arize AX 账户：在 app.arize.com 注册
2. 空间 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

零配置设置

🌐 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

Arize 导出器支持高级配置，可用于微调 OpenTelemetry 的行为：

🌐 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_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_ENDPOINT!,
  resourceAttributes: {
    "deployment.environment": process.env.NODE_ENV,
    "service.namespace": "production",
    "service.instance.id": process.env.HOSTNAME,
    "custom.attribute": "value",
  },
});

自定义元数据

🌐 Custom metadata

非保留的跨度属性会被序列化到 OpenInference metadata 载荷中，并显示在 Arize/Phoenix 中。你可以通过 tracingOptions.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",
    },
  },
});

诸如 input、output、sessionId、线程/用户 ID 和 OpenInference ID 等保留字段会自动排除。

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

OpenInference 语义约定

🌐 OpenInference Semantic Conventions

该导出器实现了面向生成式人工智能应用的OpenInference语义约定，在不同的可观测性平台之间提供标准化的追踪结构。

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

相关

🌐 Related

• 追踪概览
• 凤凰文档
• Arize AX 文档
• OpenInference 规范