DefaultExporter

@mastra/observability@1.12.0 で非推奨になり、MastraStorageExporter に置き換えられました。

非推奨

DefaultExporter は後方互換性のために維持されており、将来のメジャーバージョンで削除されます。新しいプロジェクトでは MastraStorageExporter を使用してください。両クラスのコンストラクター、設定、実行時の動作は同じです。DefaultExporter が維持する従来の mastra-default-observability-exporter exporter name により、これを対象に構築された監視ルールは引き続き機能します。

自動バッチ処理と再試行ロジックを使用して、Observability イベントを 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' - ログレベル（デフォルト：INFO）

TracingStorageStrategy

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

ストラテジーの動作

• realtime：各イベントを直ちにストレージへ永続化します
• batch-with-updates：作成と更新を別々にバッチ処理し、順番に適用します
• insert-only：SPAN_ENDED イベントのみを処理し、更新は無視します

プロパティ

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

メソッド

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 はストレージアダプターにその機能を問い合わせます。

interface TracingStrategy {
  /** Strategies supported by this adapter */
  supported: TracingStorageStrategy[]

  /** Preferred strategy for optimal performance */
  preferred: TracingStorageStrategy
}

exporter は次の処理を行います。

1. 利用可能な場合は、ストレージアダプターが推奨するストラテジーを使用する
2. 推奨ストラテジーが利用できない場合は、最初にサポートされているストラテジーへフォールバックする
3. ユーザー指定のストラテジーがサポートされていない場合は、警告をログに記録する

バッチ処理の動作

フラッシュのトリガー

次のいずれかの条件を満たすと、バッファーがフラッシュされます。

• バッファーサイズが maxBatchSize に達する
• 最初のイベントがバッファーに追加されてからの経過時間が maxBatchWaitMs を超える
• バッファーサイズが maxBufferSize に達する（緊急フラッシュ）
• shutdown() が呼び出される

再試行ロジック

失敗したフラッシュは、指数バックオフを使用して再試行されます。

• 再試行の遅延：retryDelayMs * 2^attempt
• 最大試行回数：maxRetries
• すべての再試行に失敗するとバッチは破棄される

ストレージがシグナルをサポートしていない場合、または再試行回数を使い切った場合、DefaultExporter は ObservabilityDropEvent を、exporter と bridge に登録された onDroppedEvent handler を通じて発行します。ドロップイベントには、シグナル、理由、件数、exporter 名、判明している場合はストレージ名、サニタイズ済みのエラー詳細が含まれます。

順不同イベントの処理

batch-with-updates ストラテジーの場合：

• 作成済みの Span を追跡する
• まだ作成されていない Span の更新や終了を拒否する
• 順不同イベントの警告をログに記録する
• 更新順序を維持するためにシーケンス番号を管理する

使用方法

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 連携

リファレンス

• 設定：設定オプション
• インターフェース：型定義