# Cloud exporter

The `CloudExporter` sends traces to Mastra Cloud for centralized monitoring and team collaboration. It's automatically enabled when using the default observability configuration with a valid access token.

## Configuration

### Prerequisites

1. **Mastra Cloud Account**: Sign up at [cloud.mastra.ai](https://cloud.mastra.ai)
2. **Mastra Cloud Project**: Create a project in Mastra Cloud. Traces are scoped per project, so even if you only want observability, you need a project to act as the destination for your traces.
3. **Access Token**: Generate in your project's sidebar under **Project Settings → Access Tokens**
4. **Environment Variables**: Set your credentials:

```bash
MASTRA_CLOUD_ACCESS_TOKEN=mst_xxxxxxxxxxxxxxxx
```

### Basic Setup

```typescript
import { Mastra } from '@mastra/core'
import { Observability, CloudExporter } from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'my-service',
        exporters: [
          new CloudExporter(), // Uses MASTRA_CLOUD_ACCESS_TOKEN env var
        ],
      },
    },
  }),
})
```

### Recommended Configuration

Include CloudExporter in your observability configuration:

```typescript
import { Mastra } from '@mastra/core'
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new DefaultExporter(),
          new CloudExporter(), // Sends traces to Mastra Cloud (requires MASTRA_CLOUD_ACCESS_TOKEN)
        ],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})
```

### Complete Configuration

```typescript
new CloudExporter({
  // Optional - defaults to env var
  accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,

  // Optional - for self-hosted Mastra Cloud
  endpoint: 'https://cloud.your-domain.com',

  // Batching configuration
  maxBatchSize: 1000, // Max spans per batch
  maxBatchWaitMs: 5000, // Max wait before sending batch

  // Diagnostic logging
  logLevel: 'info', // debug | info | warn | error
})
```

## Viewing traces

### Mastra Cloud Dashboard

1. Navigate to [cloud.mastra.ai](https://cloud.mastra.ai)

2. Select the project associated with your access token

3. Go to **Observability → Traces**

4. Use filters to find specific traces:

   - Service name
   - Time range
   - Trace ID
   - Error status

> **Note:** Traces are scoped to the project that issued the access token. To view traces, make sure you're viewing the same project you generated the token from.

### Features

- **Trace Timeline** - Visual execution flow
- **Span Details** - Inputs, outputs, metadata
- **Performance Metrics** - Latency, token usage
- **Team Collaboration** - Share trace links

## Performance

> **Info:** CloudExporter uses intelligent batching to optimize network usage. Traces are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.

### Batching Behavior

- Traces are batched up to `maxBatchSize` (default: 1000)
- Batches are sent when full or after `maxBatchWaitMs` (default: 5 seconds)
- Failed batches are retried with exponential backoff
- Graceful degradation if Mastra Cloud is unreachable

## Related

- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
- [DefaultExporter](https://mastra.ai/docs/observability/tracing/exporters/default)
- [Mastra Cloud Documentation](https://mastra.ai/docs/mastra-cloud/overview)