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

# CloudExporter

**新增於：** `@mastra/observability@1.8.0`。**於 `1.12.0` 棄用**，由 [`MastraPlatformExporter`](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/mastra-platform-exporter) 取代。

> **已棄用:** 保留 `CloudExporter` 是為了向後兼容，並將於未來的主要版本移除。新項目請使用 [`MastraPlatformExporter`](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/mastra-platform-exporter)。兩個類別使用相同的建構函式、環境變數及執行階段行為；`CloudExporter` 會保留原有的 `mastra-cloud-observability-exporter` 匯出器 `name` 及 `CLOUD_EXPORTER_*` 錯誤 ID，確保以它建立的監察規則繼續運作。

將 tracing span、日誌、指標、分數及意見回饋傳送至 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）

## 環境變數

如設定中未有提供，匯出器會讀取以下環境變數：

- `MASTRA_PLATFORM_ACCESS_TOKEN` - `CloudExporter` 請求的驗證權杖
- `MASTRA_PROJECT_ID` - 衍生項目範圍收集器路由（例如 `/projects/:projectId/ai/spans/publish`）時使用的項目 ID
- `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` - 可觀測性端點覆寫值。可傳入基礎來源或完整的 trace 發佈 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 端點。

**傳回：** tracing 事件獲接受並加入緩衝，或被忽略後傳回 `Promise<void>`。

### `onLogEvent`

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

處理供 Cloud 匯出的記錄訊號。

傳入此處理常式的每個 `LogEvent` 都會經過緩衝，並匯出至由已配置基礎端點衍生的 Cloud 記錄端點。與 tracing 不同，`CloudExporter` 層級不會再按事件狀態篩選。如匯出器已停用，此方法不會執行任何操作。

**傳回：** 記錄事件獲接受並加入緩衝後傳回 `Promise<void>`。

### `onMetricEvent`

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

處理供 Cloud 匯出的指標訊號。

傳入此處理常式的每個 `MetricEvent` 都會經過緩衝，並匯出至由已配置基礎端點衍生的 Cloud 指標端點。`CloudExporter` 內不會再按指標子類型或狀態篩選。除非匯出器已停用，否則它會轉送收到的每個指標事件。

**傳回：** 指標事件獲接受並加入緩衝後傳回 `Promise<void>`。

### `onScoreEvent`

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

處理供 Cloud 匯出的分數訊號。

傳入此處理常式的每個 `ScoreEvent` 都會經過緩衝，並匯出至由已配置基礎端點衍生的 Cloud 分數端點。匯出器層除了檢查匯出器是否已停用外，不會作額外篩選，因此此方法會轉送收到的所有分數事件。

**傳回：** 分數事件獲接受並加入緩衝後傳回 `Promise<void>`。

### `onFeedbackEvent`

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

處理供 Cloud 匯出的意見回饋訊號。

傳入此處理常式的每個 `FeedbackEvent` 都會經過緩衝，並匯出至由已配置基礎端點衍生的 Cloud 意見回饋端點。`CloudExporter` 內不會按意見回饋類型篩選。除非匯出器已停用，否則此處收到的所有意見回饋事件都會被轉送。

**傳回：** 意見回饋事件獲接受並加入緩衝後傳回 `Promise<void>`。

### flush

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

在不關閉匯出器的情況下，強制將所有已緩衝事件刷新至 Mastra 平台。適用於無伺服器環境，讓你可確保在執行階段終止前匯出 span。

### shutdown

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

刷新其餘事件並執行清理。

## 行為

### 驗證

如未透過設定或環境變數提供存取權杖，匯出器會：

- 記錄包含註冊資料的警告
- 不執行任何操作（捨棄所有事件）

### 批次處理

匯出器會對 tracing span、日誌、指標、分數及意見回饋進行批次處理，以有效運用網絡：

- 已緩衝事件總數達到 `maxBatchSize` 時刷新
- 自批次中第一個已緩衝訊號起經過 `maxBatchWaitMs` 時刷新
- 呼叫 `shutdown()` 時刷新

### 錯誤處理

- 使用指數退避重試，最多嘗試 `maxRetries` 次
- 所有重試均失敗後捨棄批次
- 記錄錯誤，但繼續處理新事件

### 端點路由

- 基礎來源會自動衍生訊號端點
- 如沒有 `projectId`，衍生路由會使用 `/ai/{signal}/publish`
- 如有 `projectId` 或 `MASTRA_PROJECT_ID`，衍生路由會使用 `/projects/:projectId/ai/{signal}/publish`
- 即使已配置 `projectId`，明確指定的完整發佈 URL 亦會原樣使用

### 訊號處理

- `exportTracingEvent()` 只會匯出 `SPAN_ENDED` tracing 事件
- `onLogEvent()`、`onMetricEvent()`、`onScoreEvent()` 及 `onFeedbackEvent()` 會緩衝各自收到的每個訊號類型事件
- 在 `flush()` 及 `shutdown()` 期間，所有受支援的訊號批次都會上載至各自相符的 Cloud 發佈端點

## `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/zh-HK/docs/observability/tracing/overview)：完整指南
- [匯出器](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/overview)：匯出器概念

### 其他匯出器

- [DefaultExporter](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/default-exporter)：儲存持久化
- [ConsoleExporter](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/console-exporter)：除錯輸出
- [Langfuse](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/langfuse)：Langfuse 整合
- [Braintrust](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/braintrust)：Braintrust 整合

### 參考

- [設定](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/configuration)：設定選項
- [介面](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/interfaces)：類型定義