# CloudExporter

Sends traces to Mastra Cloud for online visualization and monitoring.

## Constructor

```typescript
new CloudExporter(config?: CloudExporterConfig)
```

## CloudExporterConfig

```typescript
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

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

## Methods

### exportTracingEvent

```typescript
async exportTracingEvent(event: TracingEvent): Promise<void>
```

Processes tracing events. Only exports SPAN\_ENDED events to Cloud.

### flush

```typescript
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

```typescript
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:

```typescript
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

```typescript
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](https://mastra.ai/docs/observability/tracing/overview/llms.txt) - Complete guide
- [Exporters](https://mastra.ai/docs/observability/tracing/overview/llms.txt) - Exporter concepts

### Other Exporters

- [DefaultExporter](https://mastra.ai/reference/observability/tracing/exporters/default-exporter/llms.txt) - Storage persistence
- [ConsoleExporter](https://mastra.ai/reference/observability/tracing/exporters/console-exporter/llms.txt) - Debug output
- [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse/llms.txt) - Langfuse integration
- [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust/llms.txt) - Braintrust integration

### Reference

- [Configuration](https://mastra.ai/reference/observability/tracing/configuration/llms.txt) - Configuration options
- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces/llms.txt) - Type definitions