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 if you don't have one yet.
2. Deploy Studio to the Mastra platform with mastra studio deploy.
3. Follow the quickstart steps below 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:

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:

.env

MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>

2. Find your projectId

Run the following command:

mastra studio deploy list

The output looks similar to this:

✅ <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:

<your-project-id>

Set it as an environment variable:

.env

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:

.env

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:

.env

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.

.env

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:

src/mastra/index.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 for the full observability config shape.

If you prefer, rely entirely on environment variables:

src/mastra/index.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 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.

src/mastra/index.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.

.env

MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com

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

src/mastra/index.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 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
• DefaultExporter