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

• AI 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