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

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

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

**pnpm**:

```bash
pnpm create mastra
```

**Yarn**:

```bash
yarn create mastra
```

**Bun**:

```bash
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**:

```bash
npx mastra init
```

**pnpm**:

```bash
pnpm dlx mastra init
```

**Yarn**:

```bash
yarn dlx mastra init
```

**Bun**:

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

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

Register [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) in your observability configuration:

```typescript
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:

```typescript
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](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for storage requirements and configuration.

## View observability data

Open your project in [Mastra Platform](https://projects.mastra.ai) 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

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

**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
```

The CLI can infer platform credentials from your project environment. See the [`mastra api` CLI reference](https://mastra.ai/reference/cli/mastra) for available commands, filtering, pagination, credential resolution, and `curl` examples.

## Next steps

- 📹 [Mastra observability and Studio workshop](https://www.youtube.com/watch?v=dKO_a3RPra0)
- [Configure Mastra Platform](https://mastra.ai/docs/mastra-platform/configuration)
- [Learn about observability](https://mastra.ai/docs/observability/overview)
- [Configure `MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter)