Mastra Storage exporter

MastraStorageExporter は、設定済みのストレージバックエンドに Trace を永続化し、Studio からアクセスできるようにします。外部サービスは必要ありません。

注記

MastraStorageExporter は以前 DefaultExporter という名前でした。元の DefaultExporter クラスも後方互換性のために @mastra/observability から引き続き export されていますが、非推奨です。新しいコードでは MastraStorageExporter を使用してください。

本番環境の Observability

本番環境では、Observability データによって汎用データベースの処理能力がすぐに圧迫される可能性があります。トラフィック量の多いアプリケーションでは、Observability ストレージドメインを ClickHouse へ、composite storage を介してルーティングしてください。詳細は本番環境での推奨事項を参照してください。

設定

前提条件

1. ストレージバックエンド：ストレージ Provider（libSQL、PostgreSQL など）を設定します
2. 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()],
      },
    },
  }),
})

推奨設定

Observability の設定に 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 戦略が異なります。本番ワークロードの Observability をサポートする Provider もあれば、主にローカル開発を目的とする Provider もあります。

戦略を 'auto' に設定すると、MastraStorageExporter はストレージ Provider に最適な戦略を自動的に選択します。ストレージ Provider がサポートしていない戦略を明示的に設定すると、exporter は警告をログへ記録し、その Provider が推奨する戦略へフォールバックします。

Observability をサポートする 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	デフォルトのストレージ、開発に適しています

Observability をサポートしない Provider

次のストレージ Provider は Observability ドメインをサポートしていません。これらの Provider を使用していて Observability が必要な場合は、composite storage を使用して Observability データをサポート対象の Provider へルーティングしてください。

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

各戦略の利点

• realtime：即座に表示でき、デバッグに最適です
• batch-with-updates：スループットが10～100倍向上し、Span のライフサイクル全体を扱えます
• insert-only：データベース操作をさらに70%削減でき、分析に最適です

本番環境での推奨事項

本番環境では Observability データが急速に増加します。1回の Agent インタラクションで数百個の Span が生成されることがあり、トラフィック量の多いアプリケーションでは1日に数千件の Trace が生成される可能性があります。ほとんどの汎用データベースは、書き込み量が多い追記専用のワークロード向けに最適化されていません。

推奨：高ボリュームの本番環境には ClickHouse

ClickHouse は、高ボリュームの分析ワークロード向けに設計されたカラム指向データベースです。次の理由から、本番環境の Observability に推奨されます。

• 書き込みに最適化：毎秒数百万件の insert を処理します
• 効率的な圧縮：Trace データのストレージコストを削減します
• 高速なクエリ：カラム指向ストレージにより、Trace の検索と集約を高速に実行できます
• 時系列データをネイティブサポート：時間ベースのデータ保持とパーティショニングを組み込みでサポートします

Composite Storage の使用

Observability をサポートしない Provider（Convex や DynamoDB など）を使用している場合や、パフォーマンスを最適化したい場合は、composite storage を使用してください。他のデータをプライマリデータベースに保持したまま、Observability データを ClickHouse へルーティングできます。

バッチ処理の動作

フラッシュのトリガー

どちらのバッチ戦略（batch-with-updates と insert-only）でも、次のいずれかの条件を満たすと Trace がストレージへフラッシュされます。

1. サイズトリガー：バッファーが maxBatchSize 個の Span に達したとき
2. 時間トリガー：最初のイベントから maxBatchWaitMs が経過したとき
3. 緊急フラッシュ：バッファーが maxBufferSize の上限に近づいたとき
4. シャットダウン：保留中のすべてのイベントを強制的にフラッシュします

エラー処理

MastraStorageExporter には、本番環境で使用できる信頼性の高いエラー処理が含まれています。

• 再試行ロジック：指数バックオフ（500ms、1s、2s、4s）
• 一時的な失敗：バックオフを使用して自動的に再試行します
• 永続的な失敗：4回失敗するとバッチを破棄します
• バッファーオーバーフロー：ストレージ障害時のメモリ問題を防ぎます

破棄された Observability イベント

DefaultExporter は Observability データを永続化できない場合、構造化された drop イベントを発行します。onDroppedEvent を持つ exporter または bridge を登録すると、これらの drop をアラートまたは監視システムへ転送できます。

イベントが破棄される理由は2つあります。

• unsupported-storage：ストレージ Provider がシグナルタイプを実装していません。
• retry-exhausted：exporter がバッチを最大 maxRetries 回再試行した後、破棄しました。

次の例は、drop の詳細を監視エンドポイントへ転送する方法を示しています。

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
• Composite Storage：複数のストレージ Provider を組み合わせます
• ストレージの設定