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

# DefaultExporter

自 `@mastra/observability@1.12.0` 起**已淘汰**，請改用 [`MastraStorageExporter`](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/mastra-storage-exporter)。

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

透過自動批次處理與重試邏輯，將可觀測性事件持久化至 Mastra Storage。

## 建構函式

```typescript
new DefaultExporter(config?: DefaultExporterConfig)
```

## `DefaultExporterConfig`

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

## `TracingStorageStrategy`

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

### 策略行為

- **realtime**：立即將每個事件持久化至儲存空間
- **batch-with-updates**：分別批次處理建立與更新，並依序套用
- **insert-only**：只處理 SPAN\_ENDED 事件，忽略更新

## 屬性

```typescript
readonly name = 'mastra-default-observability-exporter';
```

## 方法

### init

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

在相依項目準備就緒後初始化 exporter。根據儲存空間能力解析 tracing 策略。

### `exportTracingEvent`

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

根據解析出的策略處理 tracing 事件。

### flush

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

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

### shutdown

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

Flush 其餘緩衝事件並執行清理。

## 自動選取策略

當 `strategy: 'auto'`（預設）時，exporter 會向 storage adapter 查詢其能力：

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

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

Exporter 將會：

1. 若 storage adapter 的偏好策略可用，則使用該策略
2. 若偏好策略不可用，則退回第一個支援的策略
3. 若使用者指定的策略不受支援，則記錄警告

## 批次處理行為

### Flush 觸發條件

符合下列任一條件時，就會 flush buffer：

- Buffer 大小達到 `maxBatchSize`
- 從第一個緩衝事件開始經過的時間超過 `maxBatchWaitMs`
- Buffer 大小達到 `maxBufferSize`（緊急 flush）
- 呼叫 `shutdown()`

### 重試邏輯

失敗的 flush 會使用指數退避重試：

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

當儲存空間不支援某個 signal 或重試次數用盡時，`DefaultExporter` 會透過 exporter 與 bridge 上註冊的 `onDroppedEvent` handler 產生 `ObservabilityDropEvent`。Drop event 包含 signal、原因、數量、exporter 名稱、已知的儲存空間名稱，以及經過清理的錯誤詳細資料。

### 順序錯亂處理

針對 `batch-with-updates` 策略：

- 追蹤已建立的 span
- 拒絕尚未建立之 span 的更新／結束事件
- 記錄順序錯亂事件的警告
- 維護 sequence number，以依序更新

## 使用方式

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

// Default configuration
const exporter = new DefaultExporter()

// Custom batching configuration
const customExporter = new DefaultExporter({
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  strategy: 'batch-with-updates',
  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

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