Skip to main content

DefaultExporter

Persists traces to Mastra's configured storage with automatic batching and retry logic.

Constructor​

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";
}

Extends BaseExporterConfig, which includes:

  • logger?: IMastraLogger - Logger instance
  • logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - Log level (default: INFO)

TracingStorageStrategy​

type TracingStorageStrategy = "realtime" | "batch-with-updates" | "insert-only";

Strategy Behaviors​

  • realtime: Immediately persists each event to storage
  • batch-with-updates: Batches creates and updates separately, applies in order
  • insert-only: Only processes SPAN_ENDED events, ignores updates

Properties​

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

Methods​

init​

init(options: InitExporterOptions): void

Initializes the exporter after dependencies are ready. Resolves tracing strategy based on storage capabilities.

exportTracingEvent​

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

Processes a tracing event according to the resolved strategy.

shutdown​

async shutdown(): Promise<void>

Flushes remaining buffered events and performs cleanup.

Automatic Strategy Selection​

When strategy: 'auto' (default), the exporter queries the storage adapter for its capabilities:

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

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

The exporter will:

  1. Use the storage adapter's preferred strategy if available
  2. Fall back to the first supported strategy if preferred isn't available
  3. Log a warning if a user-specified strategy isn't supported

Batching Behavior​

Flush Triggers​

The buffer flushes when any of these conditions are met:

  • Buffer size reaches maxBatchSize
  • Time since first buffered event exceeds maxBatchWaitMs
  • Buffer size reaches maxBufferSize (emergency flush)
  • shutdown() is called

Retry Logic​

Failed flushes are retried with exponential backoff:

  • Retry delay: retryDelayMs * 2^attempt
  • Maximum attempts: maxRetries
  • Batch is dropped after all retries fail

Out-of-Order Handling​

For batch-with-updates strategy:

  • Tracks which spans have been created
  • Rejects updates/ends for spans not yet created
  • Logs warnings for out-of-order events
  • Maintains sequence numbers for ordered updates

Usage​

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'
});

See Also​

Documentation​

Other Exporters​

Reference​