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

.env

MASTRA_CLOUD_ACCESS_TOKEN=mst_xxxxxxxxxxxxxxxx

Basic Setup

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: "my-service",
        exporters: [
          new CloudExporter(), // Uses MASTRA_CLOUD_ACCESS_TOKEN env var
        ],
      },
    },
  }),
});

Recommended Configuration

Include CloudExporter in your observability configuration:

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

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
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
• DefaultExporter
• Mastra Cloud Documentation