> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Arize exporter

[Arize](https://arize.com/) 通过开源的 [Phoenix](https://phoenix.arize.com/) 和企业级 [Arize AX](https://arize.com/generative-ai/) 为 AI 应用提供可观测性平台。Arize exporter 使用 OpenTelemetry 和 [OpenInference](https://github.com/Arize-ai/openinference/tree/main/spec) 语义约定发送 Trace，并与任何支持 OpenInference 的 OpenTelemetry 平台兼容。

## 安装

**npm**:

```bash
npm install @mastra/arize@latest
```

**pnpm**:

```bash
pnpm add @mastra/arize@latest
```

**Yarn**:

```bash
yarn add @mastra/arize@latest
```

**Bun**:

```bash
bun add @mastra/arize@latest
```

## 配置

### Phoenix 设置

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

#### 前提条件

1. **Phoenix 实例**：使用 Docker 部署，或注册 [Phoenix Cloud](https://app.phoenix.arize.com/login)
2. **Endpoint**：Phoenix endpoint URL（以 `/v1/traces` 结尾）
3. **API key**：未认证实例可选，Phoenix Cloud 必需
4. **环境变量**：设置配置

```bash
# 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：

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

#### 显式配置

你也可以直接传入凭据（优先于环境变量）：

```typescript
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 实例进行本地测试：
>
> ```bash
> 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](http://localhost:6006) 查看 Trace。

### Arize AX 设置

Arize AX 是一个企业级可观测性平台，为生产 AI 系统提供高级功能。

#### 前提条件

1. **Arize AX 账户**：在 [app.arize.com](https://app.arize.com/) 注册
2. **Space ID**：组织的 space 标识符
3. **API key**：在 Arize AX 设置中生成
4. **环境变量**：设置凭据

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

# Optional
ARIZE_PROJECT_NAME=mastra-service
```

#### 零配置设置

设置环境变量后，无需任何配置即可使用 exporter：

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

#### 显式配置

你也可以直接传入凭据（优先于环境变量）：

```typescript
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 行为：

### 完整配置

```typescript
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 的批处理和导出方式：

```typescript
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 属性

向所有导出的 span 添加自定义属性：

```typescript
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` 添加它们：

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

`input`、`output`、`sessionId`、thread/user ID 和 OpenInference ID 等保留字段会自动排除。

## OpenInference 语义约定

此 exporter 实现面向生成式 AI 应用的 [OpenInference 语义约定](https://github.com/Arize-ai/openinference/tree/main/spec)，可在不同可观测性平台间提供标准化 Trace 结构。

## 相关内容

- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [Phoenix 文档](https://docs.arize.com/phoenix)
- [Arize AX 文档](https://docs.arize.com/)
- [OpenInference 规范](https://github.com/Arize-ai/openinference/tree/main/spec)