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

# MastraPlatformExporter

**新增於：**`@mastra/observability@1.12.0`。較早版本（`@mastra/observability@1.8.0` 至 `1.11.x`）會將相同 exporter 匯出為已淘汰的 `CloudExporter`。

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

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

## 環境變數

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

- `MASTRA_PLATFORM_ACCESS_TOKEN` - `MastraPlatformExporter` 請求的驗證 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-platform-exporter';
```

為了向後相容，已淘汰的 `CloudExporter` 類別會繼續使用 `'mastra-cloud-observability-exporter'` 作為其 `name`。

## 方法

### `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 不同，`MastraPlatformExporter` 層級不會額外依事件狀態篩選。Exporter 停用時，此方法會成為 no-op。

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

### `onMetricEvent`

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

處理要匯出的指標 signal。

傳入此 handler 的每個 `MetricEvent` 都會進入 buffer，並匯出至從已設定 base endpoint 推導出的指標 endpoint。`MastraPlatformExporter` 內部不會額外依指標子類型或狀態篩選。除非 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。`MastraPlatformExporter` 內部不會依回饋類型篩選。除非 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` 次
- 所有重試皆失敗後捨棄批次
- 記錄錯誤，但繼續處理新事件

`MastraPlatformExporter` 引發的錯誤會使用 `MASTRA_PLATFORM_EXPORTER_*` `id` 前置字串。已淘汰的 `CloudExporter` 會繼續產生 `CLOUD_EXPORTER_*` `id`。

### 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

## Span wire 格式

以下說明傳送至 Mastra platform 的每個 span 形狀，僅供參考：它不會從 `@mastra/observability` 匯出，也不應 import。Exporter 會展開原始 `AnyExportedSpan`（因此保留來源欄位名稱），再疊加少量適合 platform 使用的 alias：

```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/zh-TW/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 名稱的 dashboard 或 alert 規則，能在您完成遷移前繼續運作。

## 另請參閱

### 文件

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

### 其他 Exporter

- [MastraStorageExporter](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/mastra-storage-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)：型別定義