@mastra/core/dist/docs/references/docs-studio-observability.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# Studio observability

Studio includes these observability views:

- **Metrics** for aggregate performance data
- **Traces** for individual request inspection
- **Logs** for browsing internal and application logs

All require an observability storage backend to be configured.

## Quickstart

For detailed instructions, follow the [observability instructions](https://mastra.ai/docs/observability/overview). To get up and running quickly, add the `@mastra/observability` package to your project and configure it with [LibSQL](https://mastra.ai/reference/storage/libsql) and [DuckDB](https://mastra.ai/reference/vectors/duckdb) for a local development setup that supports both traces and metrics.

**npm**:

```bash
npm install @mastra/observability @mastra/libsql @mastra/duckdb
```

**pnpm**:

```bash
pnpm add @mastra/observability @mastra/libsql @mastra/duckdb
```

**Yarn**:

```bash
yarn add @mastra/observability @mastra/libsql @mastra/duckdb
```

**Bun**:

```bash
bun add @mastra/observability @mastra/libsql @mastra/duckdb
```

Then add the following to your `src/mastra/index.ts`:

```ts
import { Mastra } from '@mastra/core/mastra'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { MastraCompositeStore } from '@mastra/core/storage'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      observability: await new DuckDBStore().getStore('observability'),
    },
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (if MASTRA_PLATFORM_ACCESS_TOKEN is set)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
        ],
      },
    },
  }),
})
```

## Mastra platform

For hosted traces, logs, and metrics across projects and deploys, see [Observability on Mastra platform](https://mastra.ai/docs/mastra-platform/observability).

## Metrics

A dashboard that summarizes agent, workflow, and tool performance over a configurable time range (last 24 hours to 30 days). The top row shows total agent runs, model cost, token consumption, and average scorer performance. Below that, detailed cards break down model usage and cost per model, token usage per agent, trace volume with completed and error counts, latency percentiles (p50 and p95), and scorer trends over time.

Visit the [metrics overview](https://mastra.ai/docs/observability/metrics/overview) for more details.

> **Note:** Metrics require a separate OLAP store for observability. Relational databases like PostgreSQL, LibSQL, etc. aren't supported for metrics. In-memory storage resets on restart.

## Traces

When you run an agent or workflow, the Observability tab displays traces that highlight the key AI operations such as model calls, tool executions, and workflow steps. Follow these traces to see how data moves, where time is spent, and what's happening under the hood.

Tracing filters out low-level framework details so your traces stay focused and readable. Visit the [tracing overview](https://mastra.ai/docs/observability/tracing/overview) for more details.

## Logs

Browse internal Mastra logs forwarded to your observability storage. Logs provide full-text search (across message content, entity names, and trace IDs), date presets (last 24 hours to 30 days), and multi-select filters for level, entity type, and entity name. Selecting a log opens a detail panel showing the full message, structured data, and metadata. If the log is correlated with a trace, you can navigate directly to the trace and span timeline.

Log forwarding is enabled by default when you configure observability. See [logging](https://mastra.ai/docs/observability/logging) for level configuration, query examples, and customization details.

## Related

- [Observability overview](https://mastra.ai/docs/observability/overview)
- [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
- [Logging](https://mastra.ai/docs/observability/logging)
- [Mastra platform observability](https://mastra.ai/docs/mastra-platform/observability)