MastraStorageExporter

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

備註

MastraStorageExporter 之前稱為 DefaultExporter。原有的 DefaultExporter class 仍會從 @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' - 日誌層級（預設值：INFO）

TracingStorageStrategy

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

策略行為

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

屬性

readonly name = 'mastra-storage-exporter';

為保持向後兼容，已棄用的 DefaultExporter class 會繼續使用 '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>

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

shutdown

async shutdown(): Promise<void>

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

自動選擇策略

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

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 所對應的更新或結束事件
• 為次序錯亂的事件記錄警告
• 維持序號，確保更新按次序進行

用法

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：

// 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 概覽：完整指南
• Exporter：exporter 概念

其他 Exporter

• MastraPlatformExporter：Mastra 平台
• ConsoleExporter：除錯輸出
• Langfuse：Langfuse 整合
• Braintrust：Braintrust 整合

參考

• 設定：設定選項
• Interface：型別定義