Observability overview

Mastra's observability system gives you visibility into every agent run, workflow step, tool call, and model interaction. Agent behavior depends on model responses, prompts, tools, memory, and workflow state, so observability helps you inspect runtime decisions from day one. It captures complementary signals that work together to help you understand what your application is doing and why.

• Configuration: Configure observability once for traces, logs, metrics, and feedback.
• Storage: Choose storage backends for persisted traces, logs, metrics aggregation, and feedback queries.
• Tracing: Records every operation as a hierarchical timeline of spans, capturing inputs, outputs, token usage, and timing.
• Logging: Forwards structured log entries from your application and Mastra internals to observability storage, correlated to traces automatically.
• Metrics: Extracts trace usage and cost data. No additional instrumentation is required.
• Feedback: Stores ratings, comments, corrections, and other review signals linked to traces and spans.
• Integrations: Choose exporters, bridges, and span processors for Studio, hosted, or external observability workflows.

When to use observability

• Debug unexpected agent behavior by inspecting the full decision path, tool calls, and model responses.
• Monitor latency across agents, workflows, and tools to identify bottlenecks.
• Track token consumption and estimated cost over time to control spending.
• Diagnose workflow failures by tracing execution through each step.
• Compare agent performance before and after prompt or model changes.

How the pieces fit together

Tracing is the foundation. When observability is configured, every agent run, workflow execution, tool call, and model interaction produces a span. Spans are organized into traces that show the full request lifecycle as a hierarchical timeline.

Metrics are derived from traces automatically. When a span ends, Mastra extracts duration, token counts, and cost estimates without any extra code. These metrics power the dashboards in Studio.

Logs are correlated to traces automatically. Every logger.info(), logger.warn(), or logger.error() call within a traced context is tagged with the current trace and span IDs. You can move through from a log entry directly to the trace that produced it.

Feedback records human review signals such as ratings, comments, and corrections. Feedback can be linked to traces and spans, then queried with the same observability store used for metrics.

These signals share correlation IDs such as trace ID, span ID, entity type, and entity name. You can use them to move from a metric spike to its traces, logs, and related feedback.

Quickstart

Install @mastra/observability and storage backends that support traces and metrics:

npm

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

pnpm

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

Yarn

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

Bun

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

Then configure observability in your Mastra instance. The following example uses composite storage to route observability data to DuckDB (which supports metrics aggregation) while keeping everything else in LibSQL:

src/mastra/index.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
        ],
        logging: {
          enabled: true,
          level: 'info',
        },
      },
    },
  }),
})

It enables tracing, log forwarding, and metrics. Mastra also supports external tracing providers like Langfuse, Datadog, and any OpenTelemetry-compatible platform. See Maintaining Studio access to keep Mastra Studio access while sending data to an external provider.

Configuration

Observability is configured once on your Mastra instance and applies across traces, logs, and metrics.

Basic config

An observability config usually contains:

• serviceName: The service identifier attached to exported observability data.
• exporters: One or more destinations for traces, logs, and derived metrics.
• spanOutputProcessors: Transformations that run before spans are exported.
• logging: Log forwarding settings for observability storage.

For destinations and processors, see Integrations overview.

Maintaining Studio access

When you add external exporters, keep MastraStorageExporter for Studio observability and/or MastraPlatformExporter for hosted Mastra platform observability.

The following example shows only the observability config. Configure storage separately.

src/mastra/observability.ts

import { Observability, MastraStorageExporter, MastraPlatformExporter } from '@mastra/observability'
import { ArizeExporter } from '@mastra/arize'

export const observability = new Observability({
  configs: {
    production: {
      serviceName: 'my-service',
      exporters: [
        new ArizeExporter({
          endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
          apiKey: process.env.PHOENIX_API_KEY,
        }),
        new MastraStorageExporter(),
        new MastraPlatformExporter(),
      ],
    },
  },
})

Flushing in serverless environments

In serverless environments, flush observability exporters before the runtime pauses or exits:

await mastra.observability.flush()

Use external storage in serverless environments instead of local file storage. See Storage for storage selection and routing.

Multi-config setup

Use multiple configs when different environments or request types need different exporters or sampling behavior. Select the active config at runtime with configSelector.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LangfuseExporter } from '@mastra/langfuse'

const storageExporter = new MastraStorageExporter()
const langfuseExporter = new LangfuseExporter()

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      development: {
        serviceName: 'my-service-dev',
        exporters: [storageExporter],
      },
      production: {
        serviceName: 'my-service-prod',
        exporters: [storageExporter, langfuseExporter],
      },
    },
    configSelector: () => process.env.NODE_ENV || 'development',
  }),
})

For trace sampling, see Tracing.

Storage

Storage determines which observability signals persist, which queries are available, and whether metrics aggregation works. Use a dedicated observability store instead of your primary application store.

Signal support

Storage support depends on the signal and workload. MastraStorageExporter can persist traces to ClickHouse, PostgreSQL, MSSQL, MongoDB, and LibSQL. Metrics require an analytics-capable store:

• DuckDB: Recommended for local testing and development.
• ClickHouse: Recommended for high-volume production observability.
• PostgresStoreVNext: Supports metrics when the observability domain is enabled. Always provide a time range to avoid full partition scans.
• Mastra platform: Use MastraPlatformExporter for hosted observability without managing the backend yourself.

For the complete provider list and supported tracing strategies, see Mastra Storage exporter. Use composite storage to route the observability domain separately when your primary store doesn't support observability or when the workload needs independent scaling.

Local development

For local development, use:

• LibSQLStore for primary application storage
• DuckDBStore for the observability domain
• MastraStorageExporter for local Studio access

Production deployment

Observability traffic is usually more write-heavy than the rest of the application. In production:

• Use MastraStorageExporter with ClickHouse for the observability domain when you keep observability in your own storage.
• Use MastraPlatformExporter for hosted Mastra platform observability instead of managing the backend yourself.
• Use composite storage when observability needs a different backend or scaling policy from your primary application data.

For backend compatibility details and exporter batching behavior, see Mastra Storage exporter.

Mastra platform

For hosted traces, logs, and metrics across projects and deploys, see Observability on Mastra platform.

Next steps

• Tracing
• Logging
• Metrics
• Feedback
• Integrations overview
• Mastra Studio
• Automatic metrics reference
• Mastra platform observability