Skip to main content

Metrics

Mastra automatically derives metrics from spans as traced operations complete. No separate metric instrumentation is required.

Mastra emits:

  • Duration metrics for agent runs, workflows, tools, model calls, and processors
  • Token usage metrics for model input and output, including detailed token categories when the provider reports them
  • Cost estimates calculated from token usage, provider, model, and an embedded pricing registry

Metrics retain trace correlation context, so you can investigate a change in a chart by finding the related span. See the Automatic metrics reference for metric names, labels, and cost fields.

When to use metrics
Direct link to When to use metrics

  • Monitor latency across agents, tools, workflows, and model calls
  • Track token consumption and estimated cost over time
  • Compare success and error rates across agents or tools
  • Measure the effect of prompt, model, or code changes

Storage support
Direct link to Storage support

Metrics require an analytics-capable observability store:

  • DuckDB through @mastra/duckdb is recommended for local development.
  • ClickHouse through @mastra/clickhouse is recommended for high-volume production workloads.
  • PostgresStoreVNext supports metrics when its observability domain is enabled.
  • In-memory storage supports metrics, but its data is lost when the process restarts.
  • Google Cloud Spanner disables metrics by default. Set disableMetrics: false only for light workloads, or route metrics to a dedicated OLAP store.

Other storage adapters, including LibSQL, MSSQL, and MongoDB, can store other observability signals but don't implement metric storage and queries.

Set up local metrics
Direct link to Set up local metrics

Install the observability, application storage, and DuckDB packages:

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

Configure a composite store that routes the observability domain to DuckDB:

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, 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()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

MastraStorageExporter persists metrics to the configured observability store and makes them available to Studio. Use MastraPlatformExporter instead, or alongside it, to send metrics to Mastra Platform.

View and query metrics
Direct link to View and query metrics

Use the Studio observability dashboard to inspect KPI cards, breakdowns, and time-series charts. For custom dashboards and analysis, use the observability store, @mastra/client-js, HTTP endpoints, or CLI described in the Metric queries reference.

In production, always include a timestamp range in metric queries. Time bounds limit the data scanned and allow partitioned backends to skip unrelated partitions or chunks.

On this page