Default Exporter
The DefaultExporter persists traces to your configured storage backend, making them accessible through the Mastra Playground. 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
- Playground integration - View traces in Mastra Playground UI
Configuration
Prerequisites
- Storage Backend: Configure a storage provider (LibSQL, PostgreSQL, etc.)
- Mastra Playground: Install for viewing traces locally
Basic Setup
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
Mastra Playground
Access your traces through the local Playground:
- Start the Playground
- Navigate to Observability
- Filter and search your local traces
- 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
| Strategy | Description | Use Case |
|---|---|---|
| realtime | Process each event immediately | Development, debugging, low traffic |
| batch-with-updates | Buffer events and batch write with full lifecycle support | Low volume Production |
| insert-only | Only process completed spans, ignore updates | High 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 Provider | Preferred Strategy | Supported Strategies | Notes |
|---|---|---|---|
| LibSQL | batch-with-updates | realtime, batch-with-updates, insert-only | Default storage, good for development |
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:
- Size trigger: Buffer reaches
maxBatchSizespans - Time trigger:
maxBatchWaitMselapsed since first event - Emergency flush: Buffer approaches
maxBufferSizelimit - 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
})