Skip to main content

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.

Use mastra init to configure platform observability while adding Mastra to an existing application, or configure it manually in a newly created Mastra project.

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. When prompted, opt into Mastra Platform Observability to configure it automatically:

npm create mastra@latest

When you select observability, the create command authenticates with Mastra Platform, provisions a platform project, and writes the credentials to your project. If you skip platform setup or use a prompt-free creation flow, follow the manual setup steps instead.

Existing non-Mastra projects
Direct link to Existing non-Mastra projects

If you already have an application, such as a Next.js app, but haven't added Mastra yet, run mastra init and enable Mastra Observability when prompted:

npx mastra init

The CLI can select an existing platform project or create a new one.

Manual setup
Direct link to 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.

Query observability data
Direct link to Query observability data

After your project is publishing traces, logs, or scores to Mastra Platform Observability, you can query that data from your terminal with the Mastra CLI or with curl.

npx mastra api trace list

For observability commands, the CLI targets the hosted observability API and can infer credentials from your project environment. See the mastra api CLI reference for available observability commands, filtering, pagination, credential resolution, and direct curl examples.

On this page