Skip to main content

Default Exporter

The DefaultExporter persists traces to your configured storage backend, making them accessible through Studio. It's automatically enabled when using the default observability configuration and requires no external services.

When to Use DefaultExporter​

DefaultExporter is ideal for:

  • Local development - Debug and analyze traces offline
  • Data ownership - Complete control over your trace data
  • Zero dependencies - No external services required
  • Studio integration - View traces in Studio

Configuration​

Prerequisites​

  1. Storage Backend: Configure a storage provider (LibSQL, PostgreSQL, etc.)
  2. Studio: Install for viewing traces locally

Basic Setup​

src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { DefaultExporter } from "@mastra/core/ai-tracing";
import { LibSQLStore } from "@mastra/libsql";

export const mastra = new Mastra({
  storage: new LibSQLStore({
    url: "file:./mastra.db", // Required for trace persistence
  }),
  observability: {
    configs: {
      local: {
        serviceName: "my-service",
        exporters: [new DefaultExporter()],
      },
    },
  },
});

Automatic Configuration​

When using the default observability configuration, DefaultExporter is automatically included:

export const mastra = new Mastra({
  storage: new LibSQLStore({
    url: "file:./mastra.db",
  }),
  observability: {
    default: { enabled: true }, // Automatically includes DefaultExporter
  },
});

Viewing Traces​

Studio​

Access your traces through Studio:

  1. Start Studio
  2. Navigate to Observability
  3. Filter and search your local traces
  4. Inspect detailed span information

Tracing Strategies​

DefaultExporter automatically selects the optimal tracing strategy based on your storage provider. You can also override this selection if needed.

Available Strategies​

StrategyDescriptionUse Case
realtimeProcess each event immediatelyDevelopment, debugging, low traffic
batch-with-updatesBuffer events and batch write with full lifecycle supportLow volume Production
insert-onlyOnly process completed spans, ignore updatesHigh volume Production

Strategy Configuration​

new DefaultExporter({
  strategy: "auto", // Default - let storage provider decide
  // or explicitly set:
  // strategy: 'realtime' | 'batch-with-updates' | 'insert-only'

  // Batching configuration (applies to both batch-with-updates and insert-only)
  maxBatchSize: 1000, // Max spans per batch
  maxBatchWaitMs: 5000, // Max wait before flushing
  maxBufferSize: 10000, // Max spans to buffer
});

Storage Provider Support​

Different storage providers support different tracing strategies.

If you set the strategy to 'auto', the DefaultExporter automatically selects the optimal strategy for the storage provider. If you set the strategy to a mode that the storage provider doesn't support, you will get an error message.

Storage ProviderPreferred StrategySupported StrategiesNotes
LibSQLbatch-with-updatesrealtime, batch-with-updates, insert-onlyDefault storage, good for development
PostgreSQLbatch-with-updatesbatch-with-updates, insert-onlyRecommended for production

Strategy Benefits​

  • realtime: Immediate visibility, best for debugging
  • batch-with-updates: 10-100x throughput improvement, full span lifecycle
  • insert-only: Additional 70% reduction in database operations, perfect for analytics

Batching Behavior​

Flush Triggers​

For both batch strategies (batch-with-updates and insert-only), traces are flushed to storage when any of these conditions are met:

  1. Size trigger: Buffer reaches maxBatchSize spans
  2. Time trigger: maxBatchWaitMs elapsed since first event
  3. Emergency flush: Buffer approaches maxBufferSize limit
  4. Shutdown: Force flush all pending events

Error Handling​

The DefaultExporter includes robust error handling for production use:

  • Retry Logic: Exponential backoff (500ms, 1s, 2s, 4s)
  • Transient Failures: Automatic retry with backoff
  • Persistent Failures: Drop batch after 4 failed attempts
  • Buffer Overflow: Prevent memory issues during storage outages

Configuration Examples​

// Zero config - recommended for most users
new DefaultExporter();

// Development override
new DefaultExporter({
  strategy: "realtime", // Immediate visibility for debugging
});

// High-throughput production
new DefaultExporter({
  maxBatchSize: 2000, // Larger batches
  maxBatchWaitMs: 10000, // Wait longer to fill batches
  maxBufferSize: 50000, // Handle longer outages
});

// Low-latency production
new DefaultExporter({
  maxBatchSize: 100, // Smaller batches
  maxBatchWaitMs: 1000, // Flush quickly
});