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

# CloudExporter

**新增於：**`@mastra/observability@1.8.0`。自 `1.12.0` 起**已淘汰**，請改用 [`MastraPlatformExporter`](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/mastra-platform-exporter)。

將 tracing span、log、指標、分數與回饋傳送至 Mastra platform，以供線上視覺化與監控。

> **已淘汰:** 保留 `CloudExporter` 是為了向後相容，並會在未來的主要版本中移除。新專案請使用 [`MastraPlatformExporter`](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/mastra-platform-exporter)。兩個類別具有相同的建構函式、環境變數與 runtime 行為；`CloudExporter` 會保留原本的 `mastra-cloud-observability-exporter` exporter `name` 與 `CLOUD_EXPORTER_*` 錯誤 ID，讓以此建立的監控規則能繼續運作。

## 建構函式

```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'` - Log 層級（預設：INFO）

## 環境變數

若設定中未提供，exporter 會讀取下列環境變數：

- `MASTRA_PLATFORM_ACCESS_TOKEN` - `CloudExporter` 請求的驗證 token
- `MASTRA_PROJECT_ID` - 推導專案範圍 collector route（例如 `/projects/:projectId/ai/spans/publish`）時使用的 Project ID
- `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` - 可觀測性 endpoint 覆寫值。可傳入 base origin 或完整的 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>
```

處理要匯出至 Mastra platform 的 tracing 事件。

只會匯出 `SPAN_ENDED` tracing 事件。`SPAN_STARTED` 與 `SPAN_UPDATED` 會被忽略。相符的 span 會先進入 buffer，並在下次 flush 時上傳至 trace endpoint。

\*\*傳回：\*\*tracing 事件已接受進入 buffer 或被忽略後，傳回 `Promise<void>`。

### `onLogEvent`

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

處理要匯出的 log signal。

傳入此 handler 的每個 `LogEvent` 都會進入 buffer，並匯出至從已設定 base endpoint 推導出的 log endpoint。與 tracing 不同，`CloudExporter` 層級不會額外依事件狀態篩選。Exporter 停用時，此方法會成為 no-op。

\*\*傳回：\*\*log 事件已接受進入 buffer 後，傳回 `Promise<void>`。

### `onMetricEvent`

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

處理要匯出的指標 signal。

傳入此 handler 的每個 `MetricEvent` 都會進入 buffer，並匯出至從已設定 base endpoint 推導出的指標 endpoint。`CloudExporter` 內部不會額外依指標子類型或狀態篩選。除非 exporter 已停用，否則會轉送收到的每個指標事件。

\*\*傳回：\*\*指標事件已接受進入 buffer 後，傳回 `Promise<void>`。

### `onScoreEvent`

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

處理要匯出的分數 signal。

傳入此 handler 的每個 `ScoreEvent` 都會進入 buffer，並匯出至從已設定 base endpoint 推導出的分數 endpoint。Exporter 層級除了檢查是否停用外，不會額外篩選，因此此方法收到的所有分數事件都會轉送。

\*\*傳回：\*\*分數事件已接受進入 buffer 後，傳回 `Promise<void>`。

### `onFeedbackEvent`

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

處理要匯出的回饋 signal。

傳入此 handler 的每個 `FeedbackEvent` 都會進入 buffer，並匯出至從已設定 base endpoint 推導出的回饋 endpoint。`CloudExporter` 內部不會依回饋類型篩選。除非 exporter 已停用，否則會轉送此處收到的所有回饋事件。

\*\*傳回：\*\*回饋事件已接受進入 buffer 後，傳回 `Promise<void>`。

### flush

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

強制將所有緩衝事件 flush 至 Mastra platform，而不關閉 exporter。這在 serverless 環境中特別實用，可確保 runtime 結束前已匯出 span。

### shutdown

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

Flush 其餘事件並執行清理。

## 行為

### 驗證

若未透過設定或環境變數提供 access token，exporter 將會：

- 記錄包含註冊資訊的警告
- 以 no-op 方式運作（捨棄所有事件）

### 批次處理

Exporter 會批次處理 tracing span、log、指標、分數與回饋，以有效運用網路：

- 緩衝事件總數達到 `maxBatchSize` 時 flush
- 從批次中的第一個緩衝 signal 開始經過 `maxBatchWaitMs` 時 flush
- 呼叫 `shutdown()` 時 flush

### 錯誤處理

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

### Endpoint 路由

- Base origin 會自動推導 signal endpoint
- 沒有 `projectId` 時，推導出的 route 使用 `/ai/{signal}/publish`
- 有 `projectId` 或 `MASTRA_PROJECT_ID` 時，推導出的 route 使用 `/projects/:projectId/ai/{signal}/publish`
- 即使已設定 `projectId`，明確的完整發布 URL 仍會原樣使用

### Signal 處理

- `exportTracingEvent()` 只匯出 `SPAN_ENDED` tracing 事件
- `onLogEvent()`、`onMetricEvent()`、`onScoreEvent()` 與 `onFeedbackEvent()` 會針對各自的 signal 類型，將收到的每個事件放入 buffer
- `flush()` 與 `shutdown()` 期間，所有支援的 signal 批次都會上傳至相符的發布 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/zh-TW/docs/observability/tracing/overview)：完整指南
- [Exporter](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/overview)：Exporter 概念

### 其他 Exporter

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

### 參考

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