CloudExporter - Mastra Observability Cloud Export Configuration

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Guide for configuring CloudExporter to send traces, logs, metrics, scores, and feedback from any Mastra app to a hosted project on the Mastra platform.

Insight

CloudExporter is part of the @mastra/observability package starting at version 1.8.0. It routes all observability data (traces, logs, metrics, scores, feedback) to the Mastra platform for centralized monitoring in Mastra Studio. The exporter requires two mandatory environment variables: MASTRA_CLOUD_ACCESS_TOKEN (created via mastra auth tokens create exporter-token or found in the Projects page under the Observability row) and MASTRA_PROJECT_ID (found via mastra studio deploy list). The CloudExporter class can be instantiated with no arguments when relying entirely on environment variables, or with explicit options including endpoint (string for custom collector URL), maxBatchSize (default 1000), maxBatchWaitMs (default 5000ms), and logLevel. For @mastra/observability versions 1.8.0 through 1.9.1, you must also set MASTRA_CLOUD_TRACES_ENDPOINT=https://observability.mastra.ai. Starting in 1.9.2, this endpoint defaults automatically. The exporter supports sending telemetry to alternative collectors by setting MASTRA_CLOUD_TRACES_ENDPOINT to either a base origin (from which it derives all publish URLs) or a full traces publish URL ending in /spans/publish. CloudExporter implements batching behavior for performance optimization, buffering events up to maxBatchSize and sending batches either when full or after maxBatchWaitMs interval, with exponential backoff retry on failures and graceful degradation when Mastra Studio is unreachable.

Hành động

1. Create an access token by running mastra auth tokens create exporter-token and save the token as MASTRA_CLOUD_ACCESS_TOKEN. Alternatively, copy the Observability token from the Mastra platform Projects page or project Overview page. 2. Find your projectId by running mastra studio deploy list and setting MASTRA_PROJECT_ID to the ID in parentheses. 3. Set both MASTRA_CLOUD_ACCESS_TOKEN and MASTRA_PROJECT_ID as environment variables. For @mastra/observability 1.8.0-1.9.1, also set MASTRA_CLOUD_TRACES_ENDPOINT=https://observability.mastra.ai. 4. Add CloudExporter to your observability config: import { Observability, CloudExporter } from ‘@mastra/observability’, then instantiate with new CloudExporter() inside the exporters array of an Observability config within your Mastra setup. Set serviceName on the observability config (not on CloudExporter itself) to a stable value for easier trace filtering in Studio. Recommended configuration includes both DefaultExporter and CloudExporter along with SensitiveDataFilter for spanOutputProcessors. To customize, pass options like new CloudExporter({ endpoint: 'https://collector.example.com', maxBatchSize: 1000, maxBatchWaitMs: 5000, logLevel: 'info' }). After deployment, access your project in Mastra Studio and use Traces/Logs pages to inspect exported data.

Kết quả

CloudExporter sends all observability data (traces, logs, metrics, scores, feedback) to the configured Mastra platform project or alternative collector endpoint. Events are batched for performance and delivered with near real-time visibility. Failed batches retry with exponential backoff, and the exporter degrades gracefully if Mastra Studio is unreachable.

Điều kiện áp dụng

Requires @mastra/[email protected] or later. For versions 1.8.0-1.9.1, MASTRA_CLOUD_TRACES_ENDPOINT must be set explicitly. Starting 1.9.2, the endpoint defaults to https://observability.mastra.ai. Self-hosted apps still require a deployed Studio project on Mastra Platform.

---

Nội dung gốc (Original)

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/[email protected] or later.
• If you use @mastra/[email protected] 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/[email protected], 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:

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:

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:

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

If you use @mastra/[email protected] through 1.9.1, also set the Mastra platform collector explicitly:

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.

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:

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:

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.

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.

MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com

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

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

Liên kết

• Nền tảng: Dev Framework · Mastra
• Nguồn: https://mastra.ai/docs/observability/tracing/exporters/cloud

Xem thêm:

• Default exporter
• Mastra Tracing - AI Observability Configuration and Usage Guide
• Arize exporter
• Studio Observability
• Observability overview