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.

flush

async flush(): Promise<void>

Force flushes any buffered events to storage without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.

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

• Tracing Overview - Complete guide
• Exporters - Exporter concepts

Other Exporters

• CloudExporter - Mastra Cloud
• ConsoleExporter - Debug output
• Langfuse - Langfuse integration
• Braintrust - Braintrust integration

Reference

• Configuration - Configuration options
• Interfaces - Type definitions