第23章 指标（Metrics）

指标

Mastra 会在被追踪的操作完成时，自动从 span 中推导出指标，无需单独编写指标埋点代码。

Mastra 会输出：

• 各类时长指标：涵盖 agent 运行、workflow、工具、模型调用和处理器
• Token 用量指标：包括模型输入和输出，若 provider 提供细分数据，还会包含详细的 token 分类
• 成本估算：基于 token 用量、provider、模型以及内置的定价表计算得出

指标会保留与 trace 的关联上下文，因此当你发现图表数据异常时，可以直接定位到相关的 span 进行排查。指标名称、标签和成本字段详见 Automatic metrics 参考文档。

何时使用指标

• 监控 agent、工具、workflow 和模型调用的延迟
• 持续追踪 token 消耗和预估成本的变化趋势
• 对比不同 agent 或工具的成功率和错误率
• 评估 prompt、模型或代码变更带来的效果

存储支持

指标需要一个支持分析功能的可观测性存储：

• 本地开发推荐使用 @mastra/duckdb（DuckDB）。
• 高流量生产环境推荐使用 @mastra/clickhouse（ClickHouse）。
• PostgresStoreVNext 在启用 observability 领域后也支持指标。
• 内存存储支持指标，但进程重启后数据会丢失。
• Google Cloud Spanner 默认禁用指标。只有在轻负载场景下才建议设置 disableMetrics: false，或者将指标路由到专用的 OLAP 存储。

其他存储适配器（包括 LibSQL、MSSQL 和 MongoDB）可以存储其他可观测性信号，但未实现指标的存储和查询。

搭建本地指标

安装可观测性、应用存储和 DuckDB 相关的包：

npmpnpmYarnBunnpm install @mastra/observability @mastra/libsql @mastra/duckdb
pnpm add @mastra/observability @mastra/libsql @mastra/duckdb
yarn add @mastra/observability @mastra/libsql @mastra/duckdb
bun add @mastra/observability @mastra/libsql @mastra/duckdb

配置一个复合存储，将 observability 领域路由到 DuckDB：

src/mastra/index.tsimport { 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 会将指标持久化到所配置的可观测性存储中，并使其可在 Studio 中查看。如需将指标发送到 Mastra Platform，可改用 MastraPlatformExporter，或与它配合使用。 查看和查询指标 使用 Studio 的可观测性仪表盘来查看 KPI 卡片、细分数据和时间序列图表。如需自定义仪表盘和分析，可使用可观测性存储、@mastra/client-js、HTTP 端点或 Metric queries 参考文档中介绍的 CLI。 在生产环境中，指标查询务必包含时间戳范围。时间边界可以限制扫描的数据量，让分区后端跳过无关的分区或数据块。 相关内容 可观测性概览 Traces 使用指南 MastraStorageExporter