CloudExporter

Sends traces to Mastra Cloud for online visualization and monitoring.

ConstructorDirect link to Constructor

new CloudExporter(config?: CloudExporterConfig)

CloudExporterConfigDirect link to 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 VariablesDirect link to 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)

PropertiesDirect link to Properties

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

MethodsDirect link to Methods

exportEventDirect link to exportEvent

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

Processes tracing events. Only exports SPAN_ENDED events to Cloud.

shutdownDirect link to shutdown

async shutdown(): Promise<void>

Flushes remaining events and performs cleanup.

BehaviorDirect link to Behavior

AuthenticationDirect link to 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)

BatchingDirect link to 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 HandlingDirect link to Error Handling

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

Event ProcessingDirect link to Event Processing

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

MastraCloudSpanRecordDirect link to 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;
}

UsageDirect link to 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,
});