CloudExporter

Sends traces to Mastra Cloud for online visualization and monitoring.

Constructor

new CloudExporter(config?: CloudExporterConfig)

CloudExporterConfig

interface CloudExporterConfig {
  /** Maximum number of spans per batch. Default: 1000 */
  maxBatchSize?: number;
  
  /** Maximum wait time before flushing in milliseconds. Default: 5000 */
  maxBatchWaitMs?: number;
  
  /** Maximum retry attempts. Default: 3 */
  maxRetries?: number;
  
  /** Cloud access token (from env or config) */
  accessToken?: string;
  
  /** Cloud AI tracing endpoint */
  endpoint?: string;
  
  /** Optional logger */
  logger?: IMastraLogger;
}

Environment Variables

The exporter reads these environment variables if not provided in config:

• MASTRA_CLOUD_ACCESS_TOKEN - Access token for authentication
• MASTRA_CLOUD_AI_TRACES_ENDPOINT - Custom endpoint (defaults to https://api.mastra.ai/ai/spans/publish)

Properties

readonly name = 'mastra-cloud-ai-tracing-exporter';

Methods

exportEvent

async exportEvent(event: AITracingEvent): Promise<void>

Processes tracing events. Only exports SPAN_ENDED events to Cloud.

shutdown

async shutdown(): Promise<void>

Flushes remaining events and performs cleanup.

Behavior

Authentication

If no access token is provided via config or environment variable, the exporter:

• Logs a warning with sign-up information
• Operates as a no-op (discards all events)

Batching

The exporter batches spans for efficient network usage:

• Flushes when batch size reaches maxBatchSize
• Flushes when maxBatchWaitMs elapsed since first span in batch
• Flushes on shutdown()

Error Handling

• Uses exponential backoff retry with maxRetries attempts
• Drops batches after all retries fail
• Logs errors but continues processing new events

Event Processing

• Only processes SPAN_ENDED events
• Ignores SPAN_STARTED and SPAN_UPDATED events
• Formats spans to MastraCloudSpanRecord format

MastraCloudSpanRecord

Internal format for cloud spans:

interface MastraCloudSpanRecord {
  traceId: string;
  spanId: string;
  parentSpanId: string | null;
  name: string;
  spanType: string;
  attributes: Record<string, any> | null;
  metadata: Record<string, any> | null;
  startedAt: Date;
  endedAt: Date | null;
  input: any;
  output: any;
  error: any;
  isEvent: boolean;
  createdAt: Date;
  updatedAt: Date | null;
}

Usage

import { CloudExporter } from '@mastra/core/ai-tracing';
 
// Uses environment variable for token
const exporter = new CloudExporter();
 
// Explicit configuration
const customExporter = new CloudExporter({
  accessToken: 'your-token',
  maxBatchSize: 500,
  maxBatchWaitMs: 2000
});

See Also

Documentation

• AI Tracing Overview - Complete guide
• Exporters - Exporter concepts

Other Exporters

• DefaultExporter - Storage persistence
• ConsoleExporter - Debug output
• Langfuse - Langfuse integration
• Braintrust - Braintrust integration

Reference

• Configuration - Configuration options
• Interfaces - Type definitions