> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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](https://mastra.ai/docs/observability/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 (for model generation spans) reads token usage data. 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](#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 only from `MODEL_GENERATION` 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 embedded 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.

### 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**: Token metrics are only emitted from `MODEL_GENERATION` 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](https://mastra.ai/docs/observability/metrics/overview)
- [Querying metrics](https://mastra.ai/docs/observability/metrics/querying)
- [Studio observability](https://mastra.ai/docs/studio/observability)