DefaultExporter

自 @mastra/observability@1.12.0 起已棄用，請改用 MastraStorageExporter。

已棄用

DefaultExporter 只為向後兼容而保留，並會在日後的主要版本中移除。新項目請使用 MastraStorageExporter。兩個類別使用相同的建構函式、設定及執行階段行為。DefaultExporter 會保留原有 exporter name：mastra-default-observability-exporter，讓以此建立的監察規則繼續運作。

透過自動批次處理及重試邏輯，將可觀測性 event 保存至 Mastra Storage。

建構函式

new DefaultExporter(config?: DefaultExporterConfig)

DefaultExporterConfig

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

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

策略行為

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

屬性

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

方法

init

init(options: InitExporterOptions): void

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

exportTracingEvent

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

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

flush

async flush(): Promise<void>

在不關閉 exporter 的情況下，強制將所有已緩衝的 event 清送至儲存空間。這對無伺服器環境十分有用，可確保 span 在執行環境終止前完成匯出。

shutdown

async shutdown(): Promise<void>

清送其餘已緩衝的 event，並執行清理工作。

自動選擇策略

當 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. 如果使用者指定的策略不受支援，便記錄警告

批次處理行為

清送觸發條件

符合以下任何條件時，buffer 便會清送：

• Buffer 大小達到 maxBatchSize
• 自第一個 event 加入 buffer 後經過的時間超過 maxBatchWaitMs
• Buffer 大小達到 maxBufferSize（緊急清送）
• 呼叫 shutdown()

重試邏輯

清送失敗時，系統會使用指數退避方式重試：

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

當儲存空間不支援某個 signal，或已用盡重試次數時，DefaultExporter 會透過在 exporter 及 bridge 上註冊的 onDroppedEvent handler 發出 ObservabilityDropEvent。該 drop event 包含 signal、原因、數量、exporter 名稱、已知的儲存空間名稱，以及經過清理的錯誤詳情。

處理次序錯亂

對於 batch-with-updates 策略：

• 追蹤已建立的 span
• 拒絕尚未建立的 span 所發出的更新／結束 event
• 為次序錯亂的 event 記錄警告
• 維護序號，確保更新按次序執行

用法

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

其他 Exporter

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

參考

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