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

# MastraStorageExporter

透過自動批次處理及重試邏輯，將 Trace 保存至 Mastra 已設定的儲存空間。

> **備註:** `MastraStorageExporter` 之前稱為 `DefaultExporter`。原有的 `DefaultExporter` class 仍會從 `@mastra/observability` 匯出，讓現有 import 可以繼續運作，但現已棄用，並將於未來的主要版本中移除。新程式碼應使用 `MastraStorageExporter`。

## 建構函式

```typescript
new MastraStorageExporter(config?: MastraStorageExporterConfig)
```

## `MastraStorageExporterConfig`

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

  /** Maximum total buffer size before emergency flush. Default: 10000 */
  maxBufferSize?: number

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

  /** Maximum number of retry attempts. Default: 4 */
  maxRetries?: number

  /** Base retry delay in milliseconds (uses exponential backoff). Default: 500 */
  retryDelayMs?: number

  /** Tracing storage strategy or 'auto' for automatic selection. Default: 'auto' */
  strategy?: TracingStorageStrategy | 'auto'
}
```

繼承 `BaseExporterConfig`，當中包括：

- `logger?: IMastraLogger` - Logger 實例
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - 日誌層級（預設值：INFO）

## `TracingStorageStrategy`

```typescript
type TracingStorageStrategy = 'realtime' | 'batch-with-updates' | 'insert-only'
```

### 策略行為

- **realtime**：立即將每個事件保存至儲存空間
- **batch-with-updates**：分開批次處理建立及更新操作，並按次序套用
- **insert-only**：只處理 SPAN\_ENDED 事件，忽略更新

## 屬性

```typescript
readonly name = 'mastra-storage-exporter';
```

為保持向後兼容，已棄用的 `DefaultExporter` class 會繼續使用 `'mastra-default-observability-exporter'` 作為其 `name`。

## 方法

### init

```typescript
init(options: InitExporterOptions): void
```

依賴套件準備好後初始化 exporter，並根據儲存空間的能力決定 tracing 策略。

### `exportTracingEvent`

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

按照已決定的策略處理 tracing 事件。

### flush

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

在不關閉 exporter 的情況下，強制將所有緩衝中的事件寫入儲存空間。這適用於無伺服器環境，讓你可確保 span 在執行環境終止前已經匯出。

### shutdown

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

寫入其餘緩衝中的事件，並執行清理。

## 自動選擇策略

當 `strategy: 'auto'`（預設值）時，exporter 會查詢儲存空間 adapter 的能力：

```typescript
interface TracingStrategy {
  /** Strategies supported by this adapter */
  supported: TracingStorageStrategy[]

  /** Preferred strategy for optimal performance */
  preferred: TracingStorageStrategy
}
```

exporter 會：

1. 如儲存空間 adapter 的首選策略可用，便使用該策略
2. 如首選策略不可用，便改用第一個支援的策略
3. 如使用者指定的策略不受支援，便記錄警告

## 批次處理行為

### 寫入觸發條件

符合以下任何條件時，便會寫入緩衝內容：

- 緩衝大小達到 `maxBatchSize`
- 自第一個事件進入緩衝後經過的時間超過 `maxBatchWaitMs`
- 緩衝大小達到 `maxBufferSize`（緊急寫入）
- 呼叫 `shutdown()`

### 重試邏輯

寫入失敗時，會使用指數退避方式重試：

- 重試延遲：`retryDelayMs * 2^attempt`
- 嘗試次數上限：`maxRetries`
- 所有重試均失敗後會捨棄該批次

### 處理次序錯亂

使用 `batch-with-updates` 策略時：

- 追蹤已建立的 span
- 拒絕尚未建立的 span 所對應的更新或結束事件
- 為次序錯亂的事件記錄警告
- 維持序號，確保更新按次序進行

## 用法

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

// Default configuration
const exporter = new MastraStorageExporter()

// Custom batching configuration
const customExporter = new MastraStorageExporter({
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  strategy: 'batch-with-updates',
  logLevel: 'debug',
})
```

## 從 `DefaultExporter` 遷移

兩個 class 使用相同的 constructor signature 及行為。要進行遷移，請替換 import 及 constructor：

```typescript
// Before
import { DefaultExporter } from '@mastra/observability'
const exporter = new DefaultExporter()

// After
import { MastraStorageExporter } from '@mastra/observability'
const exporter = new MastraStorageExporter()
```

原有的 `DefaultExporter` 會原封不動地保留，讓依據先前 exporter 名稱 `mastra-default-observability-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

- [MastraPlatformExporter](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/mastra-platform-exporter)：Mastra 平台
- [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)：設定選項
- [Interface](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/interfaces)：型別定義