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

# MastraPlatformExporter

**新增於：** `@mastra/observability@1.12.0`。較早版本（`@mastra/observability@1.8.0` 至 `1.11.x`）以已棄用的 `CloudExporter` 名稱匯出同一個 exporter。

將 tracing 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` - 推導項目範圍 collector 路由（例如 `/projects/:projectId/ai/spans/publish`）時使用的項目 ID
- `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` - 覆寫可觀測性端點。可傳入基礎來源或完整的 traces 發佈 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 平台的 tracing 事件。

只會匯出 `SPAN_ENDED` tracing 事件。`SPAN_STARTED` 及 `SPAN_UPDATED` 會被忽略。符合條件的 span 會加入緩衝區，並在下一次 flush 時上載至 traces 端點。

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

### `onLogEvent`

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

處理要匯出的日誌訊號。

傳入此處理常式的每個 `LogEvent` 都會加入緩衝區，並匯出至從已設定基礎端點推導出的 logs 端點。與 tracing 不同，`MastraPlatformExporter` 層級不會進行額外的事件狀態篩選。如果 exporter 已停用，此方法不會執行任何操作。

**傳回：** 日誌事件獲接納並加入緩衝區後，傳回 `Promise<void>`。

### `onMetricEvent`

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

處理要匯出的指標訊號。

傳入此處理常式的每個 `MetricEvent` 都會加入緩衝區，並匯出至從已設定基礎端點推導出的 metrics 端點。`MastraPlatformExporter` 內不會按指標子類型或狀態作額外篩選。除非 exporter 已停用，否則會轉送收到的每個指標事件。

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

### `onScoreEvent`

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

處理要匯出的分數訊號。

傳入此處理常式的每個 `ScoreEvent` 都會加入緩衝區，並匯出至從已設定基礎端點推導出的 scores 端點。exporter 層除了檢查 exporter 是否已停用之外，不會作額外篩選，因此此方法收到的所有分數事件都會被轉送。

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

### `onFeedbackEvent`

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

處理要匯出的意見訊號。

傳入此處理常式的每個 `FeedbackEvent` 都會加入緩衝區，並匯出至從已設定基礎端點推導出的 feedback 端點。`MastraPlatformExporter` 內不會按意見類型作篩選。除非 exporter 已停用，否則此處收到的所有意見事件都會被轉送。

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

### flush

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

強制將緩衝區內的所有事件 flush 至 Mastra 平台，而不關閉 exporter。這適用於無伺服器環境，讓你可以確保 span 在執行階段終止前已匯出。

### shutdown

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

Flush 餘下事件並執行清理。

## 行為

### 驗證

如果沒有透過設定或環境變數提供存取權杖，exporter 會：

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

### 批次處理

exporter 會將 tracing 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` tracing 事件
- `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/zh-HK/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 或警示規則，在你完成遷移前仍可繼續運作。

## 另請參閱

### 文件

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

### 其他 Exporter

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