Mastra platform exporter

The MastraPlatformExporter 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.

note

MastraPlatformExporter was previously called CloudExporter. The original CloudExporter class is still exported from @mastra/observability for backward compatibility, but it is deprecated. New code should use MastraPlatformExporter.

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. MastraPlatformExporter 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

• MastraPlatformExporter is available starting in @mastra/observability@1.12.0. In 1.8.0 through 1.11.x the same exporter ships only as CloudExporter; the constructor signature and environment variables are identical.
• In @mastra/observability@1.8.0 through 1.9.1, set MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai in addition to MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID.
• Starting in @mastra/observability@1.9.2, the exporter defaults to https://observability.mastra.ai, so MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT is only required when you want to send telemetry to a different collector.

Quickstart

To connect MastraPlatformExporter, 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_PLATFORM_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_PLATFORM_ACCESS_TOKEN=<your-platform-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 MastraPlatformExporter can authenticate and route telemetry to the correct project:

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-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_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai

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

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

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

4. Enable MastraPlatformExporter

The following example demonstrates how to add MastraPlatformExporter to your observability config:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraPlatformExporter } from '@mastra/observability'

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

Set serviceName on the observability config, not on MastraPlatformExporter 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 MastraPlatformExporter()

With MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID set, MastraPlatformExporter sends data to the Mastra platform project you configured. If you also set MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT, it sends data to that collector instead.

note

Visit MastraPlatformExporter reference for the full list of configuration options.

Recommended configuration

Include MastraStorageExporter 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,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

Complete configuration

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

.env

MASTRA_PLATFORM_OBSERVABILITY_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 MastraPlatformExporter({
  endpoint: 'https://collector.example.com',
  maxBatchSize: 1000,
  maxBatchWaitMs: 5000,
  logLevel: 'info',
})

Viewing data in Mastra Studio

After you enable MastraPlatformExporter, 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

MastraPlatformExporter 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
• MastraStorageExporter