Skip to main content

MastraStorageExporter

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

note

MastraStorageExporter was previously called DefaultExporter. The original DefaultExporter class is still exported from @mastra/observability so existing imports keep working, but it's deprecated and will be removed in a future major version. New code should use MastraStorageExporter.

Platform storage restrictions

When MASTRA_DEPLOYMENT_ID is set, this exporter is disabled by default. Set retainStorageExporterOnPlatform: true on the observability config, not the exporter constructor, to allow remote storage export. InMemoryStore (including the fallback when no storage is configured), local libSQL, embedded replicas, and DuckDB remain blocked when the adapter reports local persistence, even with the opt-in. No observability events are written to that local database, even if the initialization warning is hidden by your logging setup.

See storage export on Platform for the supported-provider table, adapter upgrade requirements, and a configuration example.

Span previews
Direct link to Span previews

MastraStorageExporter automatically generates short, readable inputPreview, outputPreview, and errorPreview summaries based on the span type. Each preview contains up to 100 characters plus an ellipsis when truncated. Full payloads remain available separately.

Constructor
Direct link to Constructor

new MastraStorageExporter(config?: MastraStorageExporterConfig)

MastraStorageExporterConfig
Direct link to mastrastorageexporterconfig

interface MastraStorageExporterConfig extends BaseExporterConfig {
/** Opt-in byte flush thresholds. Omit to keep count-based batching. */
byteBatching?: {
maxBatchBytes?: number // Default: 8 MiB
maxConcurrentWrites?: number // Default: 1
}

/** 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)

Byte batching
Direct link to Byte batching

Enable byte batching with byteBatching: {} or supply custom thresholds. The exporter ignores byte batching when the resolved strategy is realtime, which keeps its immediate, awaited writes:

new MastraStorageExporter({
byteBatching: {
maxBatchBytes: 8 * 1024 * 1024,
maxConcurrentWrites: 1,
},
})
  • maxBatchBytes triggers a write when buffered events reach 8 MiB by default. Larger records are sent intact, without truncation or size-based drops.
  • maxConcurrentWrites controls concurrent storage writes. The default is one. Update-based tracing strategies always use one write at a time to preserve span ordering.

Record-count and timer-based flush triggers still apply. Queued records are retained when storage falls behind, so queue memory can grow. Without byteBatching, the exporter keeps its existing count-based batching behavior.

Inspect the current queue with exporter.getByteBatchingStats().

TracingStorageStrategy
Direct link to tracingstoragestrategy

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

Strategy Behaviors
Direct link to 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
Direct link to Properties

readonly name = 'mastra-storage-exporter';

The deprecated DefaultExporter class continues to use 'mastra-default-observability-exporter' as its name for backward compatibility.

Methods
Direct link to Methods

init
Direct link to init

init(options: InitExporterOptions): void

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

exportTracingEvent
Direct link to exporttracingevent

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

Processes a tracing event according to the resolved strategy.

flush
Direct link to 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
Direct link to shutdown

async shutdown(): Promise<void>

Flushes remaining buffered events and performs cleanup.

Automatic strategy selection
Direct link to 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
Direct link to Batching behavior

Flush Triggers
Direct link to 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
Direct link to 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
Direct link to 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
Direct link to Usage

import { MastraStorageExporter } from '@mastra/observability'

// Default configuration
const exporter = new MastraStorageExporter()

// Custom batching configuration
const customExporter = new MastraStorageExporter({
maxBatchSize: 500,
maxBatchWaitMs: 2000,
strategy: 'batch-with-updates',
logLevel: 'debug',
})

Migrating from DefaultExporter
Direct link to migrating-from-defaultexporter

Both classes share the same constructor signature and behavior. To migrate, replace the import and constructor:

// Before
import { DefaultExporter } from '@mastra/observability'
const exporter = new DefaultExporter()

// After
import { MastraStorageExporter } from '@mastra/observability'
const exporter = new MastraStorageExporter()

The original DefaultExporter is preserved unchanged so dashboards or alert rules that match the previous mastra-default-observability-exporter exporter name keep working until you migrate.

See also
Direct link to See also

Documentation
Direct link to Documentation

Other Exporters
Direct link to Other Exporters

Reference
Direct link to Reference