Automatic metrics reference

Mastra automatically extracts performance and usage metrics from traced execution. This page is the complete reference for every metric name, label, and context field that Mastra emits.

For setup instructions, see the Metrics overview.

When Mastra emits automatic metrics

Metrics are extracted from spans when they end. The observability layer inspects each completed span, calculates duration, and reads token usage data from model generation and classifier evaluation spans. No manual instrumentation is needed.

What affects whether a metric is available

A metric reaches storage when:

1. MastraStorageExporter is configured as an exporter.
2. The storage backend supports metrics (ClickHouse, DuckDB, or Postgres v-next with the observability domain enabled).

If metrics aren't available, see troubleshooting.

Duration metrics

Duration metrics record execution time in milliseconds, calculated from the span's start and end timestamps. Each duration metric includes a status label set to ok or error, derived from the span's status.

Metric name	Span type	Description
mastra_agent_duration_ms	AGENT_RUN	Execution time of an agent run
mastra_tool_duration_ms	TOOL_CALL, MCP_TOOL_CALL, PROVIDER_TOOL_CALL	Execution time of a tool call, including MCP and provider-executed tool calls
mastra_workflow_duration_ms	WORKFLOW_RUN	Execution time of a workflow run
mastra_model_duration_ms	MODEL_GENERATION	Execution time of a model generation
mastra_processor_duration_ms	PROCESSOR_RUN	Execution time of a processor run

Token usage metrics

Token metrics are emitted from MODEL_GENERATION and CLASSIFIER_EVALUATION spans that include usage data. Token metrics require usage data from the provider.

Input token metrics

Metric name	Description
mastra_model_total_input_tokens	Total input tokens
mastra_model_input_text_tokens	Text tokens in the input prompt
mastra_model_input_cache_read_tokens	Tokens read from prompt cache (e.g. Anthropic)
mastra_model_input_cache_write_tokens	Tokens written to prompt cache
mastra_model_input_audio_tokens	Audio tokens in the input (multimodal models)
mastra_model_input_image_tokens	Image tokens in the input (vision models)

Output token metrics

Metric name	Description
mastra_model_total_output_tokens	Total output tokens
mastra_model_output_text_tokens	Text tokens in the model's output
mastra_model_output_reasoning_tokens	Reasoning / chain-of-thought tokens (e.g. OpenAI o-series)
mastra_model_output_audio_tokens	Audio tokens in the model's output
mastra_model_output_image_tokens	Output image tokens

Provider-reported detailed token categories

The detailed breakdown metrics (everything except total_input and total_output) are only emitted when the provider reports them. If a category has zero tokens, the metric is skipped for that span. Different providers report different levels of detail. For example, not all providers report cache or audio tokens.

Cost-related context

When cost context is attached

Cost context is attached to token metrics when the provider reports a valid cost for every completed model step or when the pricing registry has a matching entry for the provider and model. Mastra sums the per-step provider costs into one query total. If any completed step lacks a valid reported cost, Mastra uses the pricing registry instead of reporting a partial total. If neither source is available, token metrics are still emitted without cost fields.

A caller-supplied costContext takes precedence over provider-reported costs and pricing registry estimates. Provider-reported totals use costMetadata.source: 'provider_reported', costMetadata.scope: 'query_total', and costMetadata.reportedStepCount to identify the source, scope, and number of completed steps included in the total.

Where prices come from

The pricing registry uses model prices from models.dev. @mastra/observability includes a snapshot of these prices, and each new release of the package includes recent prices. Stored cost estimates aren't recalculated when prices change. A custom gateway can return its own pricing for models that models.dev doesn't list. These prices only fill in models that models.dev doesn't price.

When you run mastra dev, Mastra also refreshes prices from models.dev in the background once a day, and when a model has no price. Cost estimates don't wait for a refresh, so the first call to a newly released model can still have no cost. In other environments, such as production, you can turn on the refresh with MASTRA_AUTO_REFRESH_PRICING=true.

Refreshed prices are cached in ~/.cache/mastra/pricing-data.json and reused by later processes. If a refresh fails, Mastra keeps the prices it already has.

To use only the bundled snapshot, set MASTRA_AUTO_REFRESH_PRICING=false. Setting MASTRA_OFFLINE=true also turns off the refresh.

What cost fields may be included

Field	Description
provider	Provider name (e.g. openai, anthropic)
model	Model identifier (e.g. gpt-4o, claude-sonnet-4-20250514)
estimatedCost	Estimated cost from token count and pricing tier, or a total reported by the provider
costUnit	Currency unit (e.g. USD)
costMetadata	Additional pricing context, including tier information, error details, and provider-reported cost source and scope

Correlation with traces

How metrics relate to spans and trace context

Each metric carries a CorrelationContext snapshot from the span that produced it. This context is stored alongside the metric value and links a metric to the exact span and trace.

Correlation fields use these categories:

Trace correlation

• traceId: trace identifier
• spanId: span identifier
• tags: tags from the span

Entity hierarchy

• entityType, entityId, entityName: The entity that produced the metric (e.g. agent, workflow)
• parentEntityType, parentEntityId, parentEntityName: The parent entity
• rootEntityType, rootEntityId, rootEntityName: The root entity in the call chain

Identity

• userId, organizationId, resourceId: Identity context from the request
• runId, sessionId, threadId, requestId: Correlation IDs

Deployment

• environment: Deployment environment (e.g. production, staging)
• source: Source identifier
• serviceName: Service name from the observability config
• experimentId: Experiment identifier, if applicable

Why correlation helps with debugging

When you spot a spike in latency or token usage on the Metrics dashboard, correlation context lets you drill directly into the trace that produced the metric. From there you can inspect the individual span. The root cause might be a slow tool call or a large prompt. It might also be an unexpected error.

Troubleshooting

No metrics are available

• Observability is configured: Verify that your Mastra instance has an observability config with at least one exporter.
• MastraStorageExporter or MastraPlatformExporter is present: Other exporters (Datadog, Langfuse, etc.) don't surface metrics in Mastra. MastraStorageExporter is required for the local Studio dashboard, and MastraPlatformExporter is required to view metrics in Mastra platform.
• Storage supports metrics: Metrics require an analytics-capable store (ClickHouse, DuckDB, or Postgres v-next with the observability domain enabled). Other row-oriented databases (LibSQL, MSSQL) and document stores (MongoDB) aren't supported for metrics.
• Sampling isn't 0%: If sampling probability is 0 or strategy is never, all spans become no-ops and no metrics are extracted.

Duration metrics are missing

• Span has timestamps: Duration is calculated from startTime and endTime. If either is missing, the metric is skipped.
• Span type maps to a metric: Only AGENT_RUN, TOOL_CALL, MCP_TOOL_CALL, PROVIDER_TOOL_CALL, WORKFLOW_RUN, MODEL_GENERATION, and PROCESSOR_RUN spans produce duration metrics.

Token metrics are missing

• Span is a model generation or classifier evaluation: Token metrics are only emitted from MODEL_GENERATION and CLASSIFIER_EVALUATION spans.
• Provider reports usage: The model provider must include usage data in its response. Usage data is required to emit token metrics.

Related

• Metrics overview
• Metric queries
• Studio observability