# MastraPlatformExporter

**Added in:** `@mastra/observability@1.12.0`. Earlier releases (`@mastra/observability@1.8.0` through `1.11.x`) export the same exporter as the deprecated `CloudExporter`.

Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.

> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it is deprecated and will be removed in a future major version. New code should use `MastraPlatformExporter`.

## Constructor

```typescript
new MastraPlatformExporter(config?: MastraPlatformExporterConfig)
```

## `MastraPlatformExporterConfig`

```typescript
interface MastraPlatformExporterConfig extends BaseExporterConfig {
  /** Maximum number of buffered events per batch (spans, logs, metrics, scores, feedback). Default: 1000 */
  maxBatchSize?: number

  /** Maximum wait time before flushing in milliseconds. Default: 5000 */
  maxBatchWaitMs?: number

  /** Maximum retry attempts. Default: 3 */
  maxRetries?: number

  /** Mastra Observability access token (from env or config) */
  accessToken?: string

  /** Project ID for project-scoped collector routes (letters, numbers, hyphens, underscores) */
  projectId?: string

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

  /** Explicit traces endpoint override */
  tracesEndpoint?: string

  /** Explicit logs endpoint override */
  logsEndpoint?: string

  /** Explicit metrics endpoint override */
  metricsEndpoint?: string

  /** Explicit scores endpoint override */
  scoresEndpoint?: string

  /** Explicit feedback endpoint override */
  feedbackEndpoint?: 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_PLATFORM_ACCESS_TOKEN` - Authentication token for `MastraPlatformExporter` requests
- `MASTRA_PROJECT_ID` - Project ID to use when deriving project-scoped collector routes such as `/projects/:projectId/ai/spans/publish`
- `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` - Observability endpoint override. Pass either a base origin or a full traces publish URL. Defaults to `https://observability.mastra.ai` in `@mastra/observability@1.9.2` and later

## Properties

```typescript
readonly name = 'mastra-platform-exporter';
```

The deprecated `CloudExporter` class continues to use `'mastra-cloud-observability-exporter'` as its `name` for backward compatibility.

## Methods

### `exportTracingEvent`

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

Processes tracing events for export to the Mastra platform.

Only `SPAN_ENDED` tracing events are exported. `SPAN_STARTED` and `SPAN_UPDATED` are ignored. Matching spans are buffered and uploaded to the 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 export.

Every `LogEvent` passed to this handler is buffered and exported to the logs endpoint derived from the configured base endpoint. Unlike tracing, there is no additional event-status filtering at the `MastraPlatformExporter` 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 export.

Every `MetricEvent` passed to this handler is buffered and exported to the metrics endpoint derived from the configured base endpoint. There is no additional filtering by metric subtype or status inside `MastraPlatformExporter`; 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 export.

Every `ScoreEvent` passed to this handler is buffered and exported to the 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 export.

Every `FeedbackEvent` passed to this handler is buffered and exported to the feedback endpoint derived from the configured base endpoint. There is no feedback-type filtering inside `MastraPlatformExporter`; 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 the Mastra platform 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

Errors raised by `MastraPlatformExporter` use the `MASTRA_PLATFORM_EXPORTER_*` `id` prefix. The deprecated `CloudExporter` continues to emit `CLOUD_EXPORTER_*` `id`s.

### Endpoint routing

- Base origins derive signal endpoints automatically
- Without `projectId`, derived routes use `/ai/{signal}/publish`
- With `projectId` or `MASTRA_PROJECT_ID`, derived routes use `/projects/:projectId/ai/{signal}/publish`
- Explicit full publish URLs are used as-is, even when `projectId` is configured

### 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 publish endpoints during `flush()` and `shutdown()`

## Span wire format

The shape of each span sent to Mastra platform is documented here for reference only — it is not exported from `@mastra/observability` and should not be imported. The exporter spreads the original `AnyExportedSpan` (so the source field names are preserved) and layers a small set of platform-friendly aliases on top:

```typescript
type MastraPlatformSpanRecord = AnyExportedSpan & {
  // Aliases derived from the source span
  spanId: string // alias for span.id
  spanType: string // alias for span.type
  startedAt: Date // alias for span.startTime
  endedAt: Date | null // alias for span.endTime ?? null
  error: AnyExportedSpan['errorInfo'] | null

  // Stamped at export time
  createdAt: Date
  updatedAt: Date | null
}
```

The spread `AnyExportedSpan` also carries the original `id`, `type`, `name`, `traceId`, `parentSpanId`, `isRootSpan`, `isEvent`, `startTime`, `endTime`, `entityType`, `entityId`, `entityName`, `tags`, `attributes`, `metadata`, `input`, `output`, and `errorInfo`. See [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces) for `AnyExportedSpan`.

## Usage

```typescript
import { MastraPlatformExporter } from '@mastra/observability'

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

// Explicit configuration
const customExporter = new MastraPlatformExporter({
  accessToken: 'your-token',
  projectId: 'project_123',
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  logLevel: 'debug',
})
```

## Migrating from `CloudExporter`

The two classes share the same constructor signature, environment variables, and behavior. To migrate, replace the import and constructor:

```typescript
// Before
import { CloudExporter } from '@mastra/observability'
const exporter = new CloudExporter()

// After
import { MastraPlatformExporter } from '@mastra/observability'
const exporter = new MastraPlatformExporter()
```

The original `CloudExporter` is preserved unchanged so dashboards or alert rules that match the previous `CLOUD_EXPORTER_*` error IDs or `mastra-cloud-observability-exporter` exporter name keep working until you migrate.

## 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

- [MastraStorageExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-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