MastraStorageExporter

透過自動批次處理與重試邏輯，將 trace 持久化至 Mastra 所設定的儲存空間。

備註

MastraStorageExporter 先前稱為 DefaultExporter。原本的 DefaultExporter 類別仍會從 @mastra/observability 匯出，讓既有 import 繼續運作，但該類別已淘汰，並會在未來的主要版本中移除。新程式碼應使用 MastraStorageExporter。

建構函式

new MastraStorageExporter(config?: MastraStorageExporterConfig)

MastraStorageExporterConfig

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

TracingStorageStrategy

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

策略行為

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

屬性

readonly name = 'mastra-storage-exporter';

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

方法

init

init(options: InitExporterOptions): void

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

exportTracingEvent

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

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

flush

async flush(): Promise<void>

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

shutdown

async shutdown(): Promise<void>

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

自動選取策略

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

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
• 所有重試皆失敗後捨棄該批次

順序錯亂處理

針對 batch-with-updates 策略：

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

使用方式

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 遷移

兩個類別具有相同的建構函式簽章與行為。若要遷移，請替換 import 與建構函式：

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

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

原本的 DefaultExporter 會原樣保留，因此符合先前 mastra-default-observability-exporter exporter 名稱的 dashboard 或 alert 規則，能在您完成遷移前繼續運作。

另請參閱

文件

• Tracing 概覽：完整指南
• Exporter：Exporter 概念

其他 Exporter

• MastraPlatformExporter：Mastra platform
• ConsoleExporter：偵錯輸出
• Langfuse：Langfuse 整合
• Braintrust：Braintrust 整合

參考

• 設定：設定選項
• 介面：型別定義