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

# 自动指标参考

Mastra 会自动从已追踪的执行中提取性能和用量指标。本页完整列出了 Mastra 发出的每个指标名称、标签和上下文字段。

有关设置说明，请参阅[指标概览](https://mastra.zisheng.pro/docs/observability/metrics/overview)。

## Mastra 何时发出自动指标

指标会在 Span 结束时从中提取。可观测性层会检查每个已完成的 Span、计算持续时间，并从模型生成 Span 中读取 token 用量数据。无需手动插桩。

### 影响指标是否可用的因素

满足以下条件时，指标会写入存储：

1. 已将 `MastraStorageExporter` 配置为 Exporter。
2. 存储后端支持指标（ClickHouse、DuckDB，或已启用可观测性域的 Postgres v-next）。

如果指标不可用，请参阅[故障排除](#troubleshooting)。

## 持续时间指标

持续时间指标以毫秒为单位记录执行时间，根据 Span 的开始和结束时间戳计算。每个持续时间指标都包含一个 `status` 标签，其值为 `ok` 或 `error`，由 Span 的状态得出。

| 指标名称                           | Span 类型                                            | 描述                                         |
| ------------------------------ | -------------------------------------------------- | ------------------------------------------ |
| `mastra_agent_duration_ms`     | `AGENT_RUN`                                        | Agent 运行的执行时间                              |
| `mastra_tool_duration_ms`      | `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL` | Tool 调用的执行时间，包括 MCP 和 Provider 执行的 Tool 调用 |
| `mastra_workflow_duration_ms`  | `WORKFLOW_RUN`                                     | Workflow 运行的执行时间                           |
| `mastra_model_duration_ms`     | `MODEL_GENERATION`                                 | 模型生成的执行时间                                  |
| `mastra_processor_duration_ms` | `PROCESSOR_RUN`                                    | 处理器运行的执行时间                                 |

## Token 用量指标

只有包含 `usage` 数据的 `MODEL_GENERATION` Span 才会发出 token 指标。Token 指标需要 Provider 提供用量数据。

### 输入 token 指标

| 指标名称                                    | 描述                            |
| --------------------------------------- | ----------------------------- |
| `mastra_model_total_input_tokens`       | 输入 token 总数                   |
| `mastra_model_input_text_tokens`        | 输入提示词中的文本 token               |
| `mastra_model_input_cache_read_tokens`  | 从提示词缓存读取的 token（例如 Anthropic） |
| `mastra_model_input_cache_write_tokens` | 写入提示词缓存的 token                |
| `mastra_model_input_audio_tokens`       | 输入中的音频 token（多模态模型）           |
| `mastra_model_input_image_tokens`       | 输入中的图像 token（视觉模型）            |

### 输出 token 指标

| 指标名称                                   | 描述                           |
| -------------------------------------- | ---------------------------- |
| `mastra_model_total_output_tokens`     | 输出 token 总数                  |
| `mastra_model_output_text_tokens`      | 模型输出中的文本 token               |
| `mastra_model_output_reasoning_tokens` | 推理/思维链 token（例如 OpenAI o 系列） |
| `mastra_model_output_audio_tokens`     | 模型输出中的音频 token               |
| `mastra_model_output_image_tokens`     | 输出图像 token                   |

### Provider 报告的详细 token 类别

只有当 Provider 报告详细分类时，才会发出详细分类指标（除 `total_input` 和 `total_output` 外的所有指标）。如果某个类别的 token 数量为零，则该 Span 会跳过相应指标。不同 Provider 报告的详细程度不同。例如，并非所有 Provider 都会报告缓存或音频 token。

## 成本相关上下文

### 何时附加成本上下文

当 Provider 为每个已完成的模型步骤报告了有效成本，或内置定价注册表中存在与该 Provider 和模型匹配的条目时，成本上下文会附加到 token 指标。Mastra 会将各步骤的 Provider 成本相加，得到单次查询的总成本。如果任何已完成的步骤缺少有效的已报告成本，Mastra 会改用定价注册表，而不会报告不完整的总成本。如果两个来源均不可用，仍会发出 token 指标，但不包含成本字段。

调用方提供的 `costContext` 优先于 Provider 报告的成本和定价注册表估算值。Provider 报告的总成本使用 `costMetadata.source: 'provider_reported'`、`costMetadata.scope: 'query_total'` 和 `costMetadata.reportedStepCount` 来标识来源、范围以及总成本中包含的已完成步骤数量。

### 可能包含的成本字段

| 字段              | 描述                                            |
| --------------- | --------------------------------------------- |
| `provider`      | Provider 名称（例如 `openai`、`anthropic`）          |
| `model`         | 模型标识符（例如 `gpt-4o`、`claude-sonnet-4-20250514`） |
| `estimatedCost` | 根据 token 数量和定价层级估算的成本，或 Provider 报告的总成本       |
| `costUnit`      | 货币单位（例如 `USD`）                                |
| `costMetadata`  | 其他定价上下文，包括层级信息、错误详情，以及 Provider 报告的成本来源和范围    |

## 与 Trace 关联

### 指标如何关联 Span 和 Trace 上下文

每个指标都携带一份来自生成该指标的 Span 的 `CorrelationContext` 快照。此上下文与指标值一同存储，并将指标关联到具体的 Span 和 Trace。

关联字段分为以下几类：

**Trace 关联**

- `traceId`：Trace 标识符
- `spanId`：Span 标识符
- `tags`：来自 Span 的标签

**实体层级**

- `entityType`、`entityId`、`entityName`：生成该指标的实体（例如 Agent、Workflow）
- `parentEntityType`、`parentEntityId`、`parentEntityName`：父实体
- `rootEntityType`、`rootEntityId`、`rootEntityName`：调用链中的根实体

**身份**

- `userId`、`organizationId`、`resourceId`：来自请求的身份上下文
- `runId`、`sessionId`、`threadId`、`requestId`：关联 ID

**部署**

- `environment`：部署环境（例如 `production`、`staging`）
- `source`：来源标识符
- `serviceName`：来自可观测性配置的服务名称
- `experimentId`：实验标识符（如适用）

### 关联如何帮助调试

当你在 Metrics 仪表板上发现延迟或 token 用量激增时，可以借助关联上下文直接深入查看生成该指标的 Trace，然后检查其中的各个 Span。根本原因可能是缓慢的 Tool 调用或过长的提示词，也可能是意外错误。

## 故障排除

### 没有可用指标

- **已配置 Observability**：确认你的 `Mastra` 实例包含至少配置了一个 Exporter 的 `observability` 配置。
- **存在 `MastraStorageExporter` 或 `MastraPlatformExporter`**：其他 Exporter（Datadog、Langfuse 等）不会在 Mastra 中呈现指标。本地 Studio 仪表板需要 `MastraStorageExporter`，而在 Mastra 平台中查看指标需要 `MastraPlatformExporter`。
- **存储支持指标**：指标需要支持分析的存储（ClickHouse、DuckDB，或已启用可观测性域的 Postgres v-next）。其他面向行的数据库（LibSQL、MSSQL）和文档存储（MongoDB）不支持指标。
- **采样率不为 0%**：如果采样概率为 `0` 或策略为 `never`，所有 Span 都会成为 NO-OP，并且不会提取任何指标。

### 缺少持续时间指标

- **Span 包含时间戳**：持续时间根据 `startTime` 和 `endTime` 计算。如果缺少任意一个时间戳，都会跳过该指标。
- **Span 类型映射到指标**：只有 `AGENT_RUN`、`TOOL_CALL`、`MCP_TOOL_CALL`、`PROVIDER_TOOL_CALL`、`WORKFLOW_RUN`、`MODEL_GENERATION` 和 `PROCESSOR_RUN` Span 会生成持续时间指标。

### 缺少 token 指标

- **Span 是模型生成 Span**：只有 `MODEL_GENERATION` Span 会发出 token 指标。
- **Provider 报告用量**：模型 Provider 必须在响应中包含 `usage` 数据。发出 token 指标需要用量数据。

## 相关内容

- [指标概览](https://mastra.zisheng.pro/docs/observability/metrics/overview)
- [查询指标](https://mastra.zisheng.pro/docs/observability/metrics/querying)
- [Studio 可观测性](https://mastra.zisheng.pro/docs/studio/observability)