> Discover all available pages from the documentation index: https://mastra.zisheng.pro/en/llms.txt

# 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

Choose the setup path that matches your project.

### New project

Create a managed Mastra project. When prompted, opt into Mastra Platform Observability to configure it automatically:

**npm**:

```bash
npm create mastra@latest
```

**pnpm**:

```bash
pnpm create mastra
```

**Yarn**:

```bash
yarn create mastra
```

**Bun**:

```bash
bunx create-mastra
```

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](#manual-setup) steps instead.

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

**npm**:

```bash
npx mastra init
```

**pnpm**:

```bash
pnpm dlx mastra init
```

**Yarn**:

```bash
yarn dlx mastra init
```

**Bun**:

```bash
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](https://projects.mastra.ai), 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:

```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](https://mastra.zisheng.pro/en/docs/mastra-platform/configuration) for the environment variables used by platform observability.

## 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`.

**npm**:

```bash
npx mastra api trace list
```

**pnpm**:

```bash
pnpm dlx mastra api trace list
```

**Yarn**:

```bash
yarn dlx mastra api trace list
```

**Bun**:

```bash
bun x 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](https://mastra.zisheng.pro/en/reference/cli/mastra) for available observability commands, filtering, pagination, credential resolution, and direct `curl` examples.

## Related

- 📹 [Mastra observability and Studio workshop](https://www.youtube.com/watch?v=dKO_a3RPra0)