CloudExporter

Sends traces to Mastra Cloud for online visualization and monitoring.

Constructor

new CloudExporter(config?: CloudExporterConfig)

CloudExporterConfig

interface CloudExporterConfig extends BaseExporterConfig {
  /** 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 observability endpoint */
  endpoint?: string;
}

Extends BaseExporterConfig, which includes:

• logger?: IMastraLogger - Logger instance
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - Log level (default: INFO)

Environment Variables

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

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

Properties

readonly name = 'mastra-cloud-observability-exporter';

Methods

exportTracingEvent

async exportTracingEvent(event: TracingEvent): 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/observability";

// Uses environment variable for token
const exporter = new CloudExporter();

// Explicit configuration
const customExporter = new CloudExporter({
  accessToken: "your-token",
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  logLevel: 'debug'
});

See Also

Documentation

• 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