Observability overview

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Mastra observability documentation for developers configuring visibility into agent runs, workflow steps, tool calls, and model interactions using tracing, logging, and metrics signals.

Insight

Mastra’s observability system captures three complementary signals: Tracing records every operation as a hierarchical timeline of spans with inputs, outputs, token usage, and timing. Logging forwards structured log entries from application and Mastra internals to observability storage, automatically correlated to traces. Metrics extract duration, token usage, and cost data from traces without additional instrumentation. Tracing serves as the foundation—every agent run, workflow execution, tool call, and model interaction produces spans organized into traces showing the full request lifecycle. Metrics are derived from spans automatically when they end, extracting duration, token counts, and cost estimates. Logs are correlated to traces automatically—every logger.info(), logger.warn(), or logger.error() call within a traced context is tagged with current trace and span IDs. All three signals share correlation IDs (trace ID, span ID, entity type, entity name), enabling navigation between metric spikes, underlying traces, and associated logs. Supported storage backends include @mastra/libsql and @mastra/duckdb. External tracing providers include Langfuse, Datadog, and any OpenTelemetry-compatible platform. Metrics require OLAP-capable stores like DuckDB (development) or ClickHouse (production), while traces and logs work with most backends.

Hành động

Install the observability package and storage backends: npm install @mastra/observability @mastra/libsql @mastra/duckdb (also supports pnpm, yarn, bun). Configure Observability in the Mastra instance using composite storage to route observability data to DuckDB for metrics aggregation while keeping other data in LibSQL. Key configuration components include: Observability class with configs object, DefaultExporter for persisting traces to storage for Mastra Studio, CloudExporter for sending data to hosted Mastra Studio (requires MASTRA_CLOUD_ACCESS_TOKEN), and SensitiveDataFilter for redacting sensitive data like passwords, tokens, and keys in spanOutputProcessors. Service name must be specified in the default config.

Kết quả

When observability is configured, every agent run, workflow execution, tool call, and model interaction produces spans organized into traces, logs are automatically correlated with trace IDs, and metrics are extracted automatically from spans for dashboard display in Mastra Studio.

Điều kiện áp dụng

Metrics feature requires OLAP-capable storage (DuckDB for development, ClickHouse for production). CloudExporter requires MASTRA_CLOUD_ACCESS_TOKEN environment variable to be set.

---

Nội dung gốc (Original)

Observability overview

Mastra’s observability system gives you visibility into every agent run, workflow step, tool call, and model interaction. It captures three complementary signals that work together to help you understand what your application is doing and why.

• 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 duration, token usage, and cost data from traces automatically, with no additional instrumentation required.

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 navigate from a log entry directly to the trace that produced it.

All three signals share correlation IDs (trace ID, span ID, entity type, entity name), so you can jump between a metric spike, the traces behind it, and the logs within those traces.

Get started

Install @mastra/observability and a storage backend:

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:

import { Mastra } from '@mastra/core/mastra'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { MastraCompositeStore } from '@mastra/core/storage'
import {
  Observability,
  DefaultExporter,
  CloudExporter,
  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 DefaultExporter(), // Persists traces to storage for Mastra Studio
          new CloudExporter(), // Sends observability data to hosted Mastra Studio (if MASTRA_CLOUD_ACCESS_TOKEN is set)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
        ],
      },
    },
  }),
})

This enables tracing, log forwarding, and metrics. Mastra also supports external tracing providers like Langfuse, Datadog, and any OpenTelemetry-compatible platform. See Tracing for configuration details.

Storage

Not all storage backends support every signal. Traces and logs work with most backends, but metrics require an OLAP-capable store like DuckDB (development) or ClickHouse (production). For the full compatibility list, see storage provider support.

For production environments with high traffic, use composite storage to route the observability domain to a dedicated backend. See production recommendations for details.

Next steps

• Tracing
• Logging
• Metrics
• Mastra Studio
• Automatic metrics reference

Liên kết

• Nền tảng: Dev Framework · Mastra
• Nguồn: https://mastra.ai/docs/observability/overview

Xem thêm:

• Studio Observability
• Mastra Tracing - AI Observability Configuration and Usage Guide
• Datadog exporter
• Mastra Logging System Configuration
• Langfuse exporter for Mastra observability