Observability on Mastra platform

Mastra Platform Observability collects traces, logs, metrics, scores, and feedback from Mastra applications. Use it for hosted observability without deploying Studio or Server or configuring local observability storage.

Quickstart

Choose the setup path that matches your project.

New project

Create a managed Mastra project and enable Mastra Platform Observability when prompted:

npm

npm create mastra@latest

pnpm

pnpm create mastra

Yarn

yarn create mastra

Bun

bunx create-mastra

The create command authenticates with Mastra Platform and creates an observability project. It then mints an access token and writes MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID to .env.

Existing project

If you're adding Mastra to an existing application, run mastra init and enable Mastra Observability when prompted:

npm

npx mastra init

pnpm

pnpm dlx mastra init

Yarn

yarn dlx mastra init

Bun

bun x mastra init

The init command lets you select an existing platform project or create one. It then creates an access token and writes the credentials to .env.

Configure manually

Use manual configuration if you skipped platform setup or automatic provisioning failed.

1. In Mastra Platform, create or open a project.
2. Create an access token for the project's organization.
3. Copy the project ID from the project page.
4. Add both values to .env:

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
MASTRA_PROJECT_ID=<your-project-id>

Register MastraPlatformExporter in your observability configuration:

src/mastra/index.ts

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        exporters: [new MastraPlatformExporter()],
      },
    },
  }),
})

The exporter reads the access token and project ID from the environment. Keep serviceName stable so you can distinguish applications and deployments when filtering observability data.

MastraPlatformExporter sends ended spans, logs, metrics, scores, and feedback. It buffers events and sends a batch when it reaches 1,000 events or has waited five seconds. Model chunk spans aren't exported.

note

MastraPlatformExporter replaced CloudExporter. CloudExporter remains available for backward compatibility but is deprecated. Use MastraPlatformExporter for new code.

Store data locally

Add MastraStorageExporter if you also want to persist observability data to your configured Mastra storage and inspect it in local Studio:

src/mastra/index.ts

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

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

See Mastra storage exporter for storage requirements and configuration.

View observability data

Open your project in Mastra Platform to inspect exported traces, logs, metrics, and scores. A Studio or Server deployment isn't required. Query exported feedback through the hosted feedback API described below.

Use a consistent serviceName to filter data from a specific application or deployment.

Query observability data

Query hosted observability data from the terminal with the Mastra CLI:

npm

npx mastra api trace list

pnpm

pnpm dlx mastra api trace list

Yarn

yarn dlx mastra api trace list

Bun

bun x mastra api trace list

The CLI can infer platform credentials from your project environment. See the mastra api CLI reference for available commands, filtering, pagination, credential resolution, and curl examples.

You can query exported feedback over HTTP. See the Feedback API for its current status, regional endpoints, authentication, project scoping, and supported query parameters such as traceId and environment.

Import existing traces

Use mastra traces import to move existing trace history from a supported observability provider into an existing Mastra Platform project. The command reads and validates complete traces at the source, converts them into Mastra spans, then uses a shared workflow for preparation, upload, resume, and verification.

The import command currently supports Langfuse. Additional providers can use the same command workflow when their adapters are added.

Provider	Command argument	Source requirement
Langfuse	langfuse	Langfuse Cloud or self-hosted Langfuse v4 or later

Prerequisites

Before starting an import, you need:

• A Mastra Platform project.
• Mastra Platform authentication through mastra auth login, or a MASTRA_API_TOKEN and MASTRA_ORG_ID for a headless environment.
• MASTRA_PLATFORM_ACCESS_TOKEN for upload and read-back when using an interactive login. A dry run doesn't require this token.
• Credentials for a supported source provider.
• Enough local disk space to temporarily store the prepared traces.

Configure the destination

For an interactive import, sign in and select the organization that owns the destination project:

npx mastra auth login
npx mastra auth orgs switch

Interactive login authorizes project discovery. Set the Platform access token used by the destination project before uploading or verifying traces:

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<mastra-platform-access-token>

If mastra init configured observability for the project, use the token it wrote to .env. Otherwise, create an access token in Mastra Platform.

You can run --dry-run without this token because a dry run doesn't contact the collector or query API.

Specify the destination with --project, or set MASTRA_PROJECT_ID. You can use a project name, slug, or ID with --project:

npx mastra traces import langfuse --project my-project --dry-run

If MASTRA_PROJECT_ID is set, it takes precedence over --project. Without either value, the CLI uses the project linked in .mastra-project.json.

For a headless environment, set the API token and organization ID. The command uses MASTRA_API_TOKEN for project discovery, upload, and read-back. Set the project ID or pass --project:

.env

MASTRA_API_TOKEN=<mastra-api-token>
MASTRA_ORG_ID=<organization-id>
MASTRA_PROJECT_ID=<project-id>

Configure Langfuse

Create project API keys in Langfuse, then add them to .env or .env.local in the directory where you run the command:

.env

LANGFUSE_PUBLIC_KEY=<langfuse-public-key>
LANGFUSE_SECRET_KEY=<langfuse-secret-key>

Langfuse Cloud defaults to the EU region at https://cloud.langfuse.com. Set LANGFUSE_BASE_URL to the regional host for US, Japan, or HIPAA Cloud, or to the origin of a self-hosted instance:

.env

LANGFUSE_BASE_URL=https://us.cloud.langfuse.com

Preview the import

Run a dry run before uploading:

npx mastra traces import langfuse --project my-project --dry-run

The dry run reads the source, prepares valid Mastra traces locally, and reports:

• The source and destination projects.
• The fixed import window.
• Prepared and skipped trace and span counts.
• The size of the prepared local data.
• Provider warnings and skip reasons in report.json.

It doesn't upload traces. The command prints a --resume command that uploads the prepared data later without reading the source again.

Choose the import window

By default, the command selects the last 30 days, ending when the import starts. Use --from and --to to choose a smaller window:

npx mastra traces import langfuse \
  --project my-project \
  --from "$FROM" \
  --to "$TO" \
  --dry-run

Set FROM and TO to ISO 8601 dates or timestamps. The following rules apply:

• --to can't be in the future or outside the current 30-day Platform retention period.
• --from must be earlier than --to and inside the current retention period.
• The selected window can't exceed 30 days.
• If only --to is set, the default start is the later of 30 days before --to and the current retention boundary.

Trace eligibility is based on the root observation's start time. The Langfuse adapter discovers roots in the selected window and then reads all currently available observations for each selected trace. It skips the complete trace if the available parent-child tree or timestamps are invalid.

Upload and verify

Run the command without --dry-run to upload the prepared traces:

npx mastra traces import langfuse --project my-project

The CLI displays the preparation summary and asks for confirmation before upload. Pass --yes to skip this prompt in an automated environment:

npx mastra traces import langfuse --project my-project --yes

The importer keeps every trace in one upload request and checkpoints progress only after Mastra Platform acknowledges the batch. Temporary source and destination failures use bounded retries.

After every prepared trace is acknowledged, the importer reads back a deterministic sample of up to 10 traces. It verifies span IDs, parent links, names, span types, event flags, timestamps, and whether an error is present. It doesn't read back or compare input, output, attributes, metadata, or tags.

If read-back isn't available yet or a sampled trace differs, the import pauses and keeps its prepared data. Resume the import to retry verification without uploading acknowledged traces again.

Resume an import

Use the exact command printed by the CLI when a dry run, cancellation, interruption, upload failure, or paused verification leaves an import unfinished:

npx mastra traces import langfuse \
  --resume 00000000-0000-0000-0000-000000000000 \
  --project my-project

A resumed import must use the original provider and destination project. Its saved date window can't be changed, so --from, --to, and --dry-run can't be combined with --resume.

Resume behavior depends on where the command stopped:

• An interrupted preparation reads and prepares the source again.
• An interrupted upload starts with the first unacknowledged trace.
• Paused verification retries read-back without re-uploading acknowledged traces.
• A completed import reports that it's already complete and retries any remaining local cleanup.

Local files and cleanup

Import state is stored under:

~/.mastra/imports/traces/<target-project-id>/<import-id>/

File	Purpose	Lifecycle
manifest.json	Stores the source identity, date window, counts, and acknowledged progress.	Retained after completion.
traces.jsonl	Stores one complete normalized trace per line.	Retained for dry runs and unfinished imports, then removed after successful verification.
report.json	Stores counts, warnings, skip samples, and verification results.	Retained after it's written.

These files can contain trace content. Mastra creates the import directory and files with permissions restricted to the local user. Protect the machine and account that run the import.

Imported data and limits

For Langfuse imports:

• Observations become Mastra spans with their parent-child relationships and timestamps.
• Supported fields such as names, input, output, errors, model details, usage, cost, tags, and source context are mapped when present.
• Destination trace and span IDs are deterministic. Original Langfuse IDs remain in span metadata for correlation.
• Unknown Langfuse observation types become generic spans and produce a warning instead of being silently discarded.
• Only trace observations are imported. Scores, feedback, datasets, attachments, and logs aren't imported.

The shared importer also applies these limits:

• Prepared local trace data is limited to 5 GiB per import. Use a smaller date window if an import reaches this limit.
• A complete trace must fit within the importer's 4 MiB upload payload limit. A larger trace is skipped and recorded with the trace_too_large reason.
• A trace is never split between upload requests.

Review report.json after a dry run or completed import to see exactly what was prepared, skipped, acknowledged, and verified.

See the mastra traces import CLI reference for the complete option and environment-variable reference.

Next steps

• 📹 Mastra observability and Studio workshop
• Configure Mastra Platform
• Learn about observability
• Configure MastraPlatformExporter