Skip to main content

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
Direct link to Quickstart

Choose the setup path that matches your project.

New project
Direct link to New project

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

npm create mastra@latest

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
Direct link to Existing project

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

npx 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
Direct link to 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
Direct link to 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
Direct link to View observability data

Open your project in Mastra Platform to inspect exported traces, logs, metrics, scores, and feedback. A Studio or Server deployment isn't required.

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

Query observability data
Direct link to Query observability data

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

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

Next steps
Direct link to Next steps

On this page