Mastra Observability

Tracing, metrics, and structured logging for AI operations in Mastra.

Installation

npm install @mastra/observability

Quick Start

import { Mastra } from '@mastra/core';
import { Observability, MastraStorageExporter, MastraPlatformExporter } from '@mastra/observability';

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [
          new MastraStorageExporter(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra Platform
        ],
      },
    },
  }),
});

A SensitiveDataFilter span output processor is auto-applied to every configured instance by default, redacting secrets (API keys, tokens, passwords, etc.) before they reach exporters. Set sensitiveDataFilter: false on the Observability config to opt out, or pass a SensitiveDataFilterOptions object to customize it.

Features

Auto-instrumentation - Traces agent runs, LLM calls, tool executions, and workflows
Pluggable Exporters - Exporters for Studio, plus integrations for Arize, Braintrust, Langfuse, LangSmith, and OpenTelemetry
Sampling Strategies - Always, ratio-based, or custom sampling
Span Processors - Transform or filter span data before export
OpenTelemetry Compatible - Standard trace/span ID formats for integration

Architecture

ObservabilityBus

Central event router that dispatches tracing, metric, and log events to registered exporters. All handler promises are tracked for reliable flush and shutdown — no events are silently dropped.

Exporters register via registerExporter() and can optionally implement onLogEvent and onMetricEvent handlers alongside the existing exportTracingEvent.

Auto-extracted metrics

Metrics are automatically extracted from span lifecycle events by AutoExtractedMetrics:

mastra_agent_duration_ms
mastra_tool_duration_ms
mastra_workflow_duration_ms
mastra_model_duration_ms
mastra_model_total_input_tokens / mastra_model_total_output_tokens
mastra_model_input_text_tokens / mastra_model_input_cache_read_tokens / mastra_model_input_cache_write_tokens / mastra_model_input_audio_tokens / mastra_model_input_image_tokens
mastra_model_output_text_tokens / mastra_model_output_reasoning_tokens / mastra_model_output_audio_tokens / mastra_model_output_image_tokens

Auto-extracted metrics carry labels: entity_type, entity_name, status, plus model and provider on model generation spans.

Structured logging

LoggerContextImpl emits log events with automatic trace correlation (traceId, spanId), inherited tags, and entity metadata. Supports minimum log level filtering (debug/info/warn/error/fatal).

Metrics context

MetricsContextImpl provides counter, gauge, and histogram instruments. All labels pass through a CardinalityFilter that blocks high-cardinality keys (trace_id, user_id, etc.) to protect metric backends.

Span Types

WORKFLOW_RUN - Workflow execution
WORKFLOW_STEP - Individual workflow step
AGENT_RUN - Agent processing
MODEL_GENERATION - LLM API calls
TOOL_CALL - Tool execution
MCP_TOOL_CALL - MCP tool execution
PROCESSOR_RUN - Processor execution
GENERIC - Custom operations

Metrics Labels

Auto-extracted metric labels

Label	Description	Cardinality
`entity_type`	What is being measured (e.g., `agent`, `tool`, `workflow_run`)	Small enum (~9 values)
`entity_name`	Name of the entity (e.g., `researcher`, `search`)	Bounded by defined entities
`model`	LLM model ID (only on model generation spans)	Bounded by LLM providers
`provider`	LLM provider (only on model generation spans)	Bounded by LLM providers
`status`	Outcome of the operation (`ok` or `error`), on `_ended` metrics only	2 values

User-emitted metric labels (via MetricsContext)

User-emitted metrics inherit additional context labels from the active span:

Label	Description	Cardinality
`parent_type`	Entity type of the nearest parent	Same small enum
`parent_name`	Name of the nearest parent entity	Bounded by defined entities
`root_type`	Entity type of the outermost ancestor (only set when different from parent)	Same small enum
`root_name`	Name of the outermost ancestor entity	Bounded by defined entities
`service_name`	Service name from observability config	Single value per deployment

Common query patterns

Which agent is expensive? → group by entity_name where entity_type=agent
Why is this tool slow only sometimes? → group by parent_name
What's the total cost of this user-facing flow? → group by root_name
Which model is cheapest for this agent? → group by model where entity_name=X

Documentation

For configuration options, exporters, sampling strategies, and more, see the full documentation.