Skip to main content

DefaultExporter

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

Constructor​

new DefaultExporter(config?: BatchingConfig, logger?: IMastraLogger)

BatchingConfig​

interface BatchingConfig {
  /** 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 strategy or 'auto' for automatic selection. Default: 'auto' */
  strategy?: TracingStrategy | "auto";
}

TracingStrategy​

type TracingStrategy = "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 = 'tracing-default-exporter';

Methods​

__registerMastra​

__registerMastra(mastra: Mastra): void

Registers the Mastra instance. Called automatically after Mastra construction.

init​

init(): void

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

exportEvent​

async exportEvent(event: AITracingEvent): 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 AITracingStrategy {
  /** Strategies supported by this adapter */
  supported: TracingStrategy[];

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

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/core/ai-tracing";

// Default configuration
const exporter = new DefaultExporter();

// Custom batching configuration
const customExporter = new DefaultExporter({
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  strategy: "batch-with-updates",
});

See Also​

Documentation​

Other Exporters​

Reference​