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

# CloudExporter

**添加于：**`@mastra/observability@1.8.0`。**自 `1.12.0` 起弃用**，请改用 [`MastraPlatformExporter`](https://mastra.zisheng.pro/reference/observability/tracing/exporters/mastra-platform-exporter)。

> **已弃用:** 为保持向后兼容，`CloudExporter` 目前仍予以保留，但将在未来的主要版本中移除。新项目请使用 [`MastraPlatformExporter`](https://mastra.zisheng.pro/reference/observability/tracing/exporters/mastra-platform-exporter)。两个类使用相同的构造函数、环境变量和运行时行为；`CloudExporter` 会保留原有的 `mastra-cloud-observability-exporter` Exporter `name` 和 `CLOUD_EXPORTER_*` 错误 ID，确保基于它们构建的监控规则继续正常工作。

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

## 构造函数

```typescript
new CloudExporter(config?: CloudExporterConfig)
```

## `CloudExporterConfig`

```typescript
interface CloudExporterConfig extends BaseExporterConfig {
  /** Maximum number of spans per batch. Default: 1000 */
  maxBatchSize?: number

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

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

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

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

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

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

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

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

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

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

扩展 `BaseExporterConfig`，其中包含：

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

## 环境变量

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

- `MASTRA_PLATFORM_ACCESS_TOKEN` - `CloudExporter` 请求的身份验证 token
- `MASTRA_PROJECT_ID` - 用于派生项目级 collector 路由（例如 `/projects/:projectId/ai/spans/publish`）的项目 ID
- `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` - 覆盖可观测性 endpoint。可传入 base origin 或完整的 Trace publish URL。在 `@mastra/observability@1.9.2` 及更高版本中，默认值为 `https://observability.mastra.ai`

## 属性

```typescript
readonly name = 'mastra-cloud-observability-exporter';
```

## 方法

### `exportTracingEvent`

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

处理要导出到 Cloud 的 Tracing 事件。

仅导出 `SPAN_ENDED` Tracing 事件。`SPAN_STARTED` 和 `SPAN_UPDATED` 会被忽略。匹配的 Span 会进入缓冲区，并在下次刷新时上传到 Cloud Trace endpoint。

**返回：** Tracing 事件进入缓冲区或被忽略后返回 `Promise<void>`。

### `onLogEvent`

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

处理要导出到 Cloud 的日志信号。

传入此 handler 的每个 `LogEvent` 都会进入缓冲区，并导出到根据所配置 base endpoint 派生的 Cloud 日志 endpoint。与 Tracing 不同，`CloudExporter` 层不会进行额外的事件状态筛选。如果 Exporter 已被禁用，此方法不执行任何操作。

**返回：** 日志事件进入缓冲区后返回 `Promise<void>`。

### `onMetricEvent`

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

处理要导出到 Cloud 的指标信号。

传入此 handler 的每个 `MetricEvent` 都会进入缓冲区，并导出到根据所配置 base endpoint 派生的 Cloud 指标 endpoint。`CloudExporter` 内部不会按指标子类型或状态进行额外筛选。除非 Exporter 已被禁用，否则会转发收到的每个指标事件。

**返回：** 指标事件进入缓冲区后返回 `Promise<void>`。

### `onScoreEvent`

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

处理要导出到 Cloud 的 score 信号。

传入此 handler 的每个 `ScoreEvent` 都会进入缓冲区，并导出到根据所配置 base endpoint 派生的 Cloud score endpoint。除检查 Exporter 是否被禁用外，Exporter 层不会进行其他筛选，因此此方法收到的所有 score 事件都会被转发。

**返回：** score 事件进入缓冲区后返回 `Promise<void>`。

### `onFeedbackEvent`

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

处理要导出到 Cloud 的反馈信号。

传入此 handler 的每个 `FeedbackEvent` 都会进入缓冲区，并导出到根据所配置 base endpoint 派生的 Cloud 反馈 endpoint。`CloudExporter` 内部不会按反馈类型进行筛选。除非 Exporter 已被禁用，否则会转发此处收到的所有反馈事件。

**返回：** 反馈事件进入缓冲区后返回 `Promise<void>`。

### flush

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

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

### shutdown

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

刷新剩余事件并执行清理。

## 行为

### 身份验证

如果未通过配置或环境变量提供 access token，Exporter 将：

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

### 批处理

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

- 缓冲事件总数达到 `maxBatchSize` 时刷新
- 从该批次的第一个缓冲信号开始经过 `maxBatchWaitMs` 后刷新
- 调用 `shutdown()` 时刷新

### 错误处理

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

### Endpoint 路由

- 根据 base origin 自动派生各信号的 endpoint
- 没有 `projectId` 时，派生路由使用 `/ai/{signal}/publish`
- 设置 `projectId` 或 `MASTRA_PROJECT_ID` 时，派生路由使用 `/projects/:projectId/ai/{signal}/publish`
- 即使配置了 `projectId`，显式提供的完整 publish URL 也会按原样使用

### 信号处理

- `exportTracingEvent()` 仅导出 `SPAN_ENDED` Tracing 事件
- `onLogEvent()`、`onMetricEvent()`、`onScoreEvent()` 和 `onFeedbackEvent()` 会缓冲各自收到的每个信号类型事件
- 调用 `flush()` 和 `shutdown()` 时，所有受支持的信号批次都会上传到相应的 Cloud publish endpoint

## `MastraCloudSpanRecord`

Cloud Span 的内部格式：

```typescript
interface MastraCloudSpanRecord {
  traceId: string
  spanId: string
  parentSpanId: string | null
  name: string
  spanType: string
  attributes: Record<string, any> | null
  metadata: Record<string, any> | null
  startedAt: Date
  endedAt: Date | null
  input: any
  output: any
  error: any
  isEvent: boolean
  createdAt: Date
  updatedAt: Date | null
}
```

## 用法

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

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

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

## 另请参阅

### 文档

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

### 其他 Exporter

- [DefaultExporter](https://mastra.zisheng.pro/reference/observability/tracing/exporters/default-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)：类型定义