自动指标参考

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

有关设置说明，请参阅指标概览。

Mastra 何时发出自动指标

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

影响指标是否可用的因素

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

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

如果指标不可用，请参阅故障排除。

持续时间指标

持续时间指标以毫秒为单位记录执行时间，根据 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 指标需要用量数据。

相关内容

• 指标概览
• 查询指标
• Studio 可观测性