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.

flush

async flush(): Promise<void>

Force flushes any buffered events to Mastra Cloud without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.

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