Observability on Mastra platform

Observability on Mastra platform is a standalone hosted product for searchable traces, logs, and metrics across Mastra projects and deploys. Use it when you want observability without deploying Studio first or setting up local storage.

Mastra can configure platform observability during project setup. The CLI provisions a platform project, writes the required environment variables, and registers observability exporters in your Mastra config.

Quickstart

Choose the setup path that matches your project. New and existing projects can use the CLI to provision Observability automatically, while manual setup is available when you already manage platform projects and environment variables yourself.

New project

Create a new Mastra project:

npm

npm create mastra@latest

pnpm

pnpm create mastra

Yarn

yarn create mastra

Bun

bunx create-mastra

When prompted, enable Mastra Observability:

Enable Mastra Observability? (will open auth flow)

> Yes

The CLI authenticates with Mastra platform, creates a platform project, writes the required environment variables, and configures the observability exporters.

Existing non-Mastra projects

If you already have an application, such as a Next.js app, but have not added Mastra yet, 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 CLI can select an existing platform project or create a new one.

Manual setup

Create a project in Mastra Platform, add MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID to .env, then register MastraPlatformExporter in your Mastra config. Add MastraStorageExporter if you also want to persist observability events to your configured Mastra Storage:

src/mastra/index.ts

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

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

See Mastra platform configuration for the environment variables used by platform observability.