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

# MastraPlatformExporter

**引入版本：** `@mastra/observability@1.12.0`。更早的版本（`@mastra/observability@1.8.0` 至 `1.11.x`）以已弃用的 `CloudExporter` 名称导出同一个 Exporter。

将追踪 Span、日志、指标、评分和反馈发送到 Mastra 平台，以便在线可视化和监控。

> **备注:** `MastraPlatformExporter` 以前称为 `CloudExporter`。原有的 `CloudExporter` 类仍从 `@mastra/observability` 导出，因此现有 import 可以继续使用，但它已被弃用，并将在未来的主版本中移除。新代码应使用 `MastraPlatformExporter`。

## 构造函数

```typescript
new MastraPlatformExporter(config?: MastraPlatformExporterConfig)
```

## `MastraPlatformExporterConfig`

```typescript
interface MastraPlatformExporterConfig extends BaseExporterConfig {
  /** Maximum number of buffered events per batch (spans, logs, metrics, scores, feedback). Default: 1000 */
  maxBatchSize?: number

  /** Maximum wait time before flushing in milliseconds. Default: 5000 */
  maxBatchWaitMs?: number

  /** Maximum retry attempts. Default: 3 */
  maxRetries?: number

  /** Mastra Observability access token (from env or config) */
  accessToken?: string

  /** Project ID for project-scoped collector routes (letters, numbers, hyphens, underscores) */
  projectId?: string

  /** Base observability endpoint */
  endpoint?: string

  /** Explicit traces endpoint override */
  tracesEndpoint?: string

  /** Explicit logs endpoint override */
  logsEndpoint?: string

  /** Explicit metrics endpoint override */
  metricsEndpoint?: string

  /** Explicit scores endpoint override */
  scoresEndpoint?: string

  /** Explicit feedback endpoint override */
  feedbackEndpoint?: string
}
```

扩展自 `BaseExporterConfig`，其中包括：

- `logger?: IMastraLogger` - Logger 实例
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - 日志级别（默认值：INFO）

## 环境变量

如果未在配置中提供，Exporter 会读取以下环境变量：

- `MASTRA_PLATFORM_ACCESS_TOKEN` - `MastraPlatformExporter` 请求使用的身份验证令牌
- `MASTRA_PROJECT_ID` - 推导项目范围的收集器路由时使用的项目 ID，例如 `/projects/:projectId/ai/spans/publish`
- `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` - 可观测性端点覆盖值。可传入基础源地址或完整的 Trace 发布 URL。在 `@mastra/observability@1.9.2` 及更高版本中，默认值为 `https://observability.mastra.ai`

## 属性

```typescript
readonly name = 'mastra-platform-exporter';
```

为保持向后兼容，已弃用的 `CloudExporter` 类继续使用 `'mastra-cloud-observability-exporter'` 作为其 `name`。

## 方法

### `exportTracingEvent`

```typescript
async exportTracingEvent(event: TracingEvent): Promise<void>
```

处理要导出到 Mastra 平台的追踪事件。

仅导出 `SPAN_ENDED` 追踪事件。`SPAN_STARTED` 和 `SPAN_UPDATED` 会被忽略。匹配的 Span 将进入缓冲区，并在下一次 flush 时上传到 Trace 端点。

**返回值：** 在追踪事件被接受并进入缓冲区或被忽略后返回 `Promise<void>`。

### `onLogEvent`

```typescript
async onLogEvent(event: LogEvent): Promise<void>
```

处理要导出的日志信号。

传入此处理程序的每个 `LogEvent` 都会进入缓冲区，并导出到根据配置的基础端点推导出的日志端点。与追踪不同，`MastraPlatformExporter` 层不会执行额外的事件状态过滤。如果 Exporter 已禁用，此方法不会执行任何操作。

**返回值：** 在日志事件被接受并进入缓冲区后返回 `Promise<void>`。

### `onMetricEvent`

```typescript
async onMetricEvent(event: MetricEvent): Promise<void>
```

处理要导出的指标信号。

传入此处理程序的每个 `MetricEvent` 都会进入缓冲区，并导出到根据配置的基础端点推导出的指标端点。`MastraPlatformExporter` 内部不会再按指标子类型或状态进行过滤。除非 Exporter 已禁用，否则它会转发收到的每个指标事件。

**返回值：** 在指标事件被接受并进入缓冲区后返回 `Promise<void>`。

### `onScoreEvent`

```typescript
async onScoreEvent(event: ScoreEvent): Promise<void>
```

处理要导出的评分信号。

传入此处理程序的每个 `ScoreEvent` 都会进入缓冲区，并导出到根据配置的基础端点推导出的评分端点。除了检查 Exporter 是否已禁用外，Exporter 层不会执行额外过滤，因此此方法收到的所有评分事件都会被转发。

**返回值：** 在评分事件被接受并进入缓冲区后返回 `Promise<void>`。

### `onFeedbackEvent`

```typescript
async onFeedbackEvent(event: FeedbackEvent): Promise<void>
```

处理要导出的反馈信号。

传入此处理程序的每个 `FeedbackEvent` 都会进入缓冲区，并导出到根据配置的基础端点推导出的反馈端点。`MastraPlatformExporter` 内部不会按反馈类型进行过滤。除非 Exporter 已禁用，否则此处收到的所有反馈事件都会被转发。

**返回值：** 在反馈事件被接受并进入缓冲区后返回 `Promise<void>`。

### flush

```typescript
async flush(): Promise<void>
```

强制将缓冲区中的所有事件 flush 到 Mastra 平台，而不关闭 Exporter。适用于需要确保在运行时终止前导出 Span 的无服务器环境。

### shutdown

```typescript
async shutdown(): Promise<void>
```

Flush 剩余事件并执行清理。

## 行为

### 身份验证

如果未通过配置或环境变量提供访问令牌，Exporter 将：

- 记录一条包含注册信息的警告
- 不执行任何操作（丢弃所有事件）

### 批处理

Exporter 会对追踪 Span、日志、指标、评分和反馈进行批处理，以提高网络使用效率：

- 当缓冲区中的事件总数达到 `maxBatchSize` 时 flush
- 从批次中的第一个信号进入缓冲区起，经过 `maxBatchWaitMs` 后 flush
- 调用 `shutdown()` 时 flush

### 错误处理

- 使用指数退避重试，最多尝试 `maxRetries` 次
- 所有重试均失败后丢弃批次
- 记录错误，但继续处理新事件

`MastraPlatformExporter` 引发的错误使用 `MASTRA_PLATFORM_EXPORTER_*` `id` 前缀。已弃用的 `CloudExporter` 继续发出使用 `CLOUD_EXPORTER_*` `id` 的错误。

### 端点路由

- 基础源地址会自动推导出各信号端点
- 未设置 `projectId` 时，推导出的路由使用 `/ai/{signal}/publish`
- 设置 `projectId` 或 `MASTRA_PROJECT_ID` 后，推导出的路由使用 `/projects/:projectId/ai/{signal}/publish`
- 即使配置了 `projectId`，显式指定的完整发布 URL 也会按原样使用

### 信号处理

- `exportTracingEvent()` 仅导出 `SPAN_ENDED` 追踪事件
- `onLogEvent()`、`onMetricEvent()`、`onScoreEvent()` 和 `onFeedbackEvent()` 会将各自信号类型中收到的每个事件放入缓冲区
- 在 `flush()` 和 `shutdown()` 期间，所有受支持的信号批次都会上传到对应的发布端点

## Span 传输格式

这里记录发送到 Mastra 平台的每个 Span 的结构，仅供参考：它不从 `@mastra/observability` 导出，也不应被 import。Exporter 会展开原始 `AnyExportedSpan`（因此会保留源字段名称），并在其上添加一小组便于平台使用的别名：

```typescript
type MastraPlatformSpanRecord = AnyExportedSpan & {
  // Aliases derived from the source span
  spanId: string // alias for span.id
  spanType: string // alias for span.type
  startedAt: Date // alias for span.startTime
  endedAt: Date | null // alias for span.endTime ?? null
  error: AnyExportedSpan['errorInfo'] | null

  // Stamped at export time
  createdAt: Date
  updatedAt: Date | null
}
```

展开后的 `AnyExportedSpan` 还包含原始的 `id`、`type`、`name`、`traceId`、`parentSpanId`、`isRootSpan`、`isEvent`、`startTime`、`endTime`、`entityType`、`entityId`、`entityName`、`tags`、`attributes`、`metadata`、`input`、`output` 和 `errorInfo`。有关 `AnyExportedSpan` 的信息，请参阅[接口](https://mastra.zisheng.pro/reference/observability/tracing/interfaces)。

## 用法

```typescript
import { MastraPlatformExporter } from '@mastra/observability'

// Uses environment variable for token
const exporter = new MastraPlatformExporter()

// Explicit configuration
const customExporter = new MastraPlatformExporter({
  accessToken: 'your-token',
  projectId: 'project_123',
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  logLevel: 'debug',
})
```

## 从 `CloudExporter` 迁移

这两个类具有相同的构造函数签名、环境变量和行为。要进行迁移，请替换 import 和构造函数：

```typescript
// Before
import { CloudExporter } from '@mastra/observability'
const exporter = new CloudExporter()

// After
import { MastraPlatformExporter } from '@mastra/observability'
const exporter = new MastraPlatformExporter()
```

原始 `CloudExporter` 会保持不变，因此匹配先前 `CLOUD_EXPORTER_*` 错误 ID 或 `mastra-cloud-observability-exporter` Exporter 名称的仪表板或告警规则，可以在迁移前继续正常工作。

## 另请参阅

### 文档

- [追踪概述](https://mastra.zisheng.pro/docs/observability/tracing/overview)：完整指南
- [Exporter](https://mastra.zisheng.pro/docs/observability/integrations/overview)：Exporter 概念

### 其他 Exporter

- [MastraStorageExporter](https://mastra.zisheng.pro/reference/observability/tracing/exporters/mastra-storage-exporter)：存储持久化
- [ConsoleExporter](https://mastra.zisheng.pro/reference/observability/tracing/exporters/console-exporter)：调试输出
- [Langfuse](https://mastra.zisheng.pro/reference/observability/tracing/exporters/langfuse)：Langfuse 集成
- [Braintrust](https://mastra.zisheng.pro/reference/observability/tracing/exporters/braintrust)：Braintrust 集成

### 参考

- [配置](https://mastra.zisheng.pro/reference/observability/tracing/configuration)：配置选项
- [接口](https://mastra.zisheng.pro/reference/observability/tracing/interfaces)：类型定义