# CloudExporter

Sends tracing spans, logs, metrics, scores, and feedback 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

  /** Base cloud observability endpoint */
  endpoint?: string

  /** Explicit cloud traces endpoint override */
  tracesEndpoint?: 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` - Project-scoped access token for authentication (generate in your Mastra Cloud project under **Project Settings → Access Tokens**)
- `MASTRA_CLOUD_TRACES_ENDPOINT` - Base cloud endpoint (defaults to `https://api.mastra.ai`)

## Properties

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

## Methods

### `exportTracingEvent`

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

Processes tracing events for Cloud export.

Only `SPAN_ENDED` tracing events are exported. `SPAN_STARTED` and `SPAN_UPDATED` are ignored. Matching spans are buffered and uploaded to the Cloud traces endpoint on the next flush.

**Returns:** `Promise<void>` after the tracing event has been accepted for buffering or ignored.

### `onLogEvent`

```typescript
async onLogEvent(event: LogEvent): Promise<void>
```

Processes log signals for Cloud export.

Every `LogEvent` passed to this handler is buffered and exported to the Cloud logs endpoint derived from the configured base endpoint. Unlike tracing, there is no additional event-status filtering at the `CloudExporter` level. If the exporter is disabled, this method becomes a no-op.

**Returns:** `Promise<void>` after the log event has been accepted for buffering.

### `onMetricEvent`

```typescript
async onMetricEvent(event: MetricEvent): Promise<void>
```

Processes metric signals for Cloud export.

Every `MetricEvent` passed to this handler is buffered and exported to the Cloud metrics endpoint derived from the configured base endpoint. There is no additional filtering by metric subtype or status inside `CloudExporter`; the exporter forwards every metric event it receives unless it is disabled.

**Returns:** `Promise<void>` after the metric event has been accepted for buffering.

### `onScoreEvent`

```typescript
async onScoreEvent(event: ScoreEvent): Promise<void>
```

Processes score signals for Cloud export.

Every `ScoreEvent` passed to this handler is buffered and exported to the Cloud scores endpoint derived from the configured base endpoint. There is no extra filtering at the exporter layer beyond the disabled-exporter check, so all score events received by this method are forwarded.

**Returns:** `Promise<void>` after the score event has been accepted for buffering.

### `onFeedbackEvent`

```typescript
async onFeedbackEvent(event: FeedbackEvent): Promise<void>
```

Processes feedback signals for Cloud export.

Every `FeedbackEvent` passed to this handler is buffered and exported to the Cloud feedback endpoint derived from the configured base endpoint. There is no feedback-type filtering inside `CloudExporter`; all feedback events received here are forwarded unless the exporter is disabled.

**Returns:** `Promise<void>` after the feedback event has been accepted for buffering.

### 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 tracing spans, logs, metrics, scores, and feedback for efficient network usage:

- Flushes when total buffered event count reaches `maxBatchSize`
- Flushes when `maxBatchWaitMs` elapsed since the first buffered signal in the 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

### Signal Processing

- `exportTracingEvent()` only exports `SPAN_ENDED` tracing events
- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for their respective signal type
- All supported signal batches are uploaded to their matching Cloud publish endpoints during `flush()` and `shutdown()`

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

### Other Exporters

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

### Reference

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