# Cloud exporter

The `CloudExporter` sends traces, logs, metrics, scores, and feedback to the Mastra platform. Use it to route observability data from any Mastra app to a hosted project in the Mastra platform.

> **Self-hosted or standalone apps:** If you host your Mastra application on your own infrastructure (not on Mastra Platform), you still need a deployed Studio project to view traces, logs, and metrics. `CloudExporter` sends data to a Studio project, so one must exist before you can use it.
>
> 1. [Create a Mastra project](https://mastra.ai/guides/getting-started/quickstart) if you don't have one yet.
> 2. [Deploy Studio](https://mastra.ai/docs/studio/deployment) to the Mastra platform with `mastra studio deploy`.
> 3. Follow the [quickstart steps below](#quickstart) to create an access token and find your project ID.

## Version compatibility

- Use `CloudExporter` with `@mastra/observability@1.8.0` or later.
- If you use `@mastra/observability@1.8.0` through `1.9.1`, set `MASTRA_CLOUD_TRACES_ENDPOINT=https://observability.mastra.ai` in addition to `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID`.
- Starting in `@mastra/observability@1.9.2`, `CloudExporter` defaults to `https://observability.mastra.ai`, so `MASTRA_CLOUD_TRACES_ENDPOINT` is only required when you want to send telemetry to a different collector.

## Quickstart

To connect `CloudExporter`, create an access token, find the destination `projectId`, and add the exporter to your observability config.

### 1. Create an access token

Run the following command:

```bash
mastra auth tokens create exporter-token
```

This command prints a token secret that you can use as `MASTRA_CLOUD_ACCESS_TOKEN`.

If you already have an access token, copy the **Observability** value from the Mastra platform instead. You can find it in either of these places:

- On the **Projects** page, open the project list and find the **Observability** row on the project card.
- On the project **Overview** page, find the **Observability** row directly below the deployment URL.

Set the token as an environment variable:

```bash
MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>
```

### 2. Find your `projectId`

Run the following command:

```bash
mastra studio deploy list
```

The output looks similar to this:

```text
✅ <your-project-name> (<your-project-id>)
   Latest:   00000000-0000-0000-0000-000000000000 — running
   URL:      https://260407.studio.mastra.cloud
```

In this output, the value in parentheses is the `projectId`:

```text
<your-project-id>
```

Set it as an environment variable:

```bash
MASTRA_PROJECT_ID=<your-project-id>
```

### 3. Set your environment variables

Set both values in your environment so `CloudExporter` can authenticate and route telemetry to the correct project:

```bash
MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>
MASTRA_PROJECT_ID=<your-project-id>
```

If you use `@mastra/observability@1.8.0` through `1.9.1`, also set the Mastra platform collector explicitly:

```bash
MASTRA_CLOUD_TRACES_ENDPOINT=https://observability.mastra.ai
```

If you want to send telemetry somewhere other than Mastra platform, set `MASTRA_CLOUD_TRACES_ENDPOINT` as well. Pass either a base origin or a full traces publish URL ending in `/spans/publish`.

```bash
MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com
```

When you pass a base origin, `CloudExporter` derives the matching publish URLs for traces, logs, metrics, scores, and feedback automatically.

### 4. Enable `CloudExporter`

The following example demonstrates how to add `CloudExporter` to your observability config:

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'api-server',
        exporters: [new CloudExporter()],
      },
    },
  }),
})
```

Set `serviceName` on the observability config, not on `CloudExporter` itself.

Use a stable `serviceName` value. In Studio, traces can be filtered by **Deployments → Service Name**, so a consistent name makes traces easier to find.

Visit [Observability configuration reference](https://mastra.ai/reference/observability/tracing/configuration) for the full observability config shape.

If you prefer, rely entirely on environment variables:

```ts
new CloudExporter()
```

With `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `CloudExporter` sends data to the Mastra platform project you configured. If you also set `MASTRA_CLOUD_TRACES_ENDPOINT`, it sends data to that collector instead.

> **Note:** Visit [CloudExporter reference](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter) for the full list of configuration options.

## Recommended configuration

Include `DefaultExporter` if you also want to inspect local traces in Studio or persist observability data to your configured storage.

```ts
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()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})
```

## Complete configuration

`CloudExporter` defaults to Mastra platform. If you want to send telemetry to a different collector, set `MASTRA_CLOUD_TRACES_ENDPOINT` in your environment or pass `endpoint` in code.

```bash
MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com
```

The following example demonstrates how to override the collector endpoint and batching behavior in code:

```ts
new CloudExporter({
  endpoint: 'https://collector.example.com',
  maxBatchSize: 1000,
  maxBatchWaitMs: 5000,
  logLevel: 'info',
})
```

## Viewing data in Mastra Studio

After you enable `CloudExporter`, open your project in [Mastra Studio](https://projects.mastra.ai) to inspect the exported data.

- Open the project you set `MASTRA_PROJECT_ID` to and select **Open Studio**.
- In Studio, go to **Traces** to inspect agent and workflow traces.
- Open the filter menu and use **Deployments → Service Name** to isolate traces from a specific app or deployment.
- Use the **Logs** page in the project dashboard to inspect exported logs.

When you deploy with Mastra Studio, set **Deployment → Service Name** to a stable value and keep it aligned with the `serviceName` in your observability config. This makes traces easier to filter in Studio through **Deployments → Service Name** when multiple services or deployments send data to the same project.

## Performance

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

### Batching behavior

- Events 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.
- The exporter degrades gracefully if Mastra Studio is unreachable.

## Related

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