Mastra Storage exporter

MastraStorageExporter 會將 Trace 持久保存至你已設定的儲存後端，讓你可透過 Studio 存取，毋須使用任何外部服務。

備註

MastraStorageExporter 之前稱為 DefaultExporter。為向後兼容，原有的 DefaultExporter class 仍會從 @mastra/observability export，但現已棄用。新程式碼應使用 MastraStorageExporter。

生產環境可觀測性

在生產環境中，可觀測性資料可迅速令通用資料庫不勝負荷。對於高流量應用程式，請透過複合儲存，將可觀測性儲存 domain 路由至 ClickHouse。詳情請參閱生產環境建議。

設定

前置條件

1. 儲存後端：設定儲存 Provider（libSQL、PostgreSQL 等）
2. Studio：安裝 Studio，以便在本機檢視 Trace

基本設定

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db', // Required for trace persistence
  }),
  observability: new Observability({
    configs: {
      local: {
        serviceName: 'my-service',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})

建議設定

在可觀測性設定中加入 MastraStorageExporter：

import { Mastra } from '@mastra/core'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (requires MASTRA_PLATFORM_ACCESS_TOKEN)
        ],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

Studio

透過 Studio 存取你的 Trace：

1. 啟動 Studio
2. 前往 Observability
3. 篩選及搜尋本機 Trace
4. 查看詳細的 span 資訊

Tracing 策略

MastraStorageExporter 會根據你的儲存 Provider，自動選擇最佳的 Tracing 策略。如有需要，你亦可覆寫此選擇。

可用策略

策略	說明	使用情境
realtime	即時處理每個事件	開發、除錯、低流量
batch-with-updates	緩衝事件並批次寫入，完整支援整個生命週期	低流量生產環境
insert-only	只處理已完成的 span，忽略更新	高流量生產環境

策略設定

new MastraStorageExporter({
  strategy: 'auto', // Default - let storage provider decide
  // or explicitly set:
  // strategy: 'realtime' | 'batch-with-updates' | 'insert-only'

  // Batching configuration (applies to both batch-with-updates and insert-only)
  maxBatchSize: 1000, // Max spans per batch
  maxBatchWaitMs: 5000, // Max wait before flushing
  maxBufferSize: 10000, // Max spans to buffer
})

儲存 Provider 支援

不同的儲存 Provider 支援不同的 Tracing 策略。部分 Provider 支援生產工作負載的可觀測性，另一些則主要供本機開發使用。

如果將策略設為 'auto'，MastraStorageExporter 會自動為該儲存 Provider 選擇最佳策略。如果你明確設定了儲存 Provider 不支援的策略，exporter 會記錄警告，並改用該 Provider 的首選策略。

支援可觀測性的 Provider

儲存 Provider	首選策略	支援的策略	建議用途
ClickHouse	insert-only	insert-only	生產環境（高流量）
PostgreSQL	batch-with-updates	batch-with-updates, insert-only	生產環境（低流量）
MSSQL	batch-with-updates	batch-with-updates, insert-only	生產環境（低流量）
MongoDB	batch-with-updates	batch-with-updates, insert-only	生產環境（低流量）
OracleDB	batch-with-updates	batch-with-updates, insert-only	生產環境（低流量）
libSQL	batch-with-updates	batch-with-updates, insert-only	預設儲存，適合開發使用

不支援可觀測性的 Provider

以下儲存 Provider 不支援可觀測性 domain。如果你正在使用其中一個 Provider 並需要可觀測性功能，請使用複合儲存，將可觀測性資料路由至支援此功能的 Provider：

• Convex
• DynamoDB
• Cloudflare D1
• Cloudflare Durable Objects
• Upstash
• LanceDB

策略優點

• realtime：即時可見，最適合除錯
• batch-with-updates：吞吐量提升 10 至 100 倍，完整支援 span 生命週期
• insert-only：資料庫操作額外減少 70%，非常適合分析用途

生產環境建議

可觀測性資料在生產環境中增長迅速。一次 Agent 互動可產生數百個 span，而高流量應用程式每日可產生數千個 Trace。大多數通用資料庫並未針對這類大量寫入、只附加的工作負載進行最佳化。

建議：在高流量生產環境使用 ClickHouse

ClickHouse 是專為高容量分析工作負載而設的列式資料庫。建議在生產環境中使用它儲存可觀測性資料，原因如下：

• 針對寫入最佳化：每秒可處理數百萬次 insert
• 高效壓縮：降低 Trace 資料的儲存成本
• 快速查詢：列式儲存可快速查找及彙總 Trace
• 原生支援時間序列：內置支援按時間保留及分割資料

使用複合儲存

如果你使用不支援可觀測性的 Provider（例如 Convex 或 DynamoDB），或希望改善效能，請使用複合儲存，將可觀測性資料路由至 ClickHouse，同時將其他資料保留在主要資料庫中。

批次處理行為

Flush 觸發條件

對於兩種批次策略（batch-with-updates 及 insert-only），只要符合以下任何一項條件，Trace 就會 flush 至儲存空間：

1. 大小觸發：buffer 中的 span 數目達到 maxBatchSize
2. 時間觸發：自第一個事件起已經過 maxBatchWaitMs
3. 緊急 flush：buffer 接近 maxBufferSize 上限
4. 關閉：強制 flush 所有待處理事件

錯誤處理

MastraStorageExporter 具備可靠的錯誤處理機制，適合在生產環境使用：

• 重試邏輯：指數退避（500ms、1s、2s、4s）
• 暫時性故障：使用退避機制自動重試
• 持續性故障：嘗試 4 次仍失敗後捨棄該批次
• buffer 溢出：避免儲存服務中斷期間出現記憶體問題

被捨棄的可觀測性事件

當 DefaultExporter 無法持久保存可觀測性資料時，會發出結構化的捨棄事件。註冊具備 onDroppedEvent 的 exporter 或 bridge，將這些捨棄事件轉發至警報或監察系統。

事件會因以下兩個原因被捨棄：

• unsupported-storage：儲存 Provider 未實作該 signal 類型。
• retry-exhausted：exporter 對一個批次重試最多 maxRetries 次後仍告失敗，因而將其捨棄。

以下範例示範如何將捨棄事件的詳細資料轉發至監察 endpoint：

src/mastra/observability.ts

import { BaseExporter } from '@mastra/observability'
import type { ObservabilityDropEvent, TracingEvent } from '@mastra/core/observability'

class DropAlertExporter extends BaseExporter {
  name = 'drop-alerts'

  async onDroppedEvent(event: ObservabilityDropEvent) {
    await fetch('https://monitoring.example.com/observability-drops', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        count: event.count,
        signal: event.signal,
        reason: event.reason,
        exporterName: event.exporterName,
      }),
    })
  }

  protected async _exportTracingEvent(_event: TracingEvent) {}
}

設定範例

// Zero config - recommended for most users
new MastraStorageExporter()

// Development override
new MastraStorageExporter({
  strategy: 'realtime', // Immediate visibility for debugging
})

// High-throughput production
new MastraStorageExporter({
  maxBatchSize: 2000, // Larger batches
  maxBatchWaitMs: 10000, // Wait longer to fill batches
  maxBufferSize: 50000, // Handle longer outages
})

// Low-latency production
new MastraStorageExporter({
  maxBatchSize: 100, // Smaller batches
  maxBatchWaitMs: 1000, // Flush quickly
})

相關內容

• Tracing 概覽
• MastraPlatformExporter
• 複合儲存：結合多個儲存 Provider
• 儲存設定