指标概览

Mastra 会从已追踪的执行中自动发出性能和用量指标，无需手动埋点。指标会在 span 完成时从中派生。

以下类别的指标会自动发出：

• 持续时间指标：Agent、Workflow、Tool、模型调用和 processor 的执行时间。
• Token 用量指标：按类型（文本、缓存、音频、图像、推理）细分的输入和输出 token 数量。
• 成本估算：根据内置定价注册表估算每次模型调用的成本。

备注

指标需要支持分析的可观测性存储。大多数关系型数据库（LibSQL、MSSQL）不支持指标。内存存储会在重启时重置。

本地开发请通过 @mastra/duckdb 使用 DuckDB。生产环境请通过 @mastra/clickhouse 使用 ClickHouse。启用 observability domain 的 PostgresStoreVNext 也支持指标，但请始终提供时间范围，避免扫描完整分区。

Google Cloud Spanner 支持指标，但不建议用于高负载指标工作负载。由于指标具有高写入量和高扫描量，Spanner adapter 默认禁用指标。仅对轻量工作负载设置 disableMetrics: false，或者将指标路由到 OLAP 存储。

何时使用指标

• 监控 Agent、Tool、Workflow 和模型调用的延迟
• 跟踪 token 消耗和成本随时间的变化趋势
• 通过比较成功率和错误率，找出错误频发的 Agent 或 Tool
• 比较 prompt、模型或代码更改前后的性能

开始使用

安装所需软件包：

npm

npm install @mastra/observability @mastra/libsql @mastra/duckdb

pnpm

pnpm add @mastra/observability @mastra/libsql @mastra/duckdb

Yarn

yarn add @mastra/observability @mastra/libsql @mastra/duckdb

Bun

bun add @mastra/observability @mastra/libsql @mastra/duckdb

然后使用 composite store 配置可观测性，将 observability domain 路由到 DuckDB：

src/mastra/index.ts

import { 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()],
      },
    },
  }),
})

Studio

Studio 指标仪表板通过 KPI 卡片、详细分组、token 用量时间线和可配置时间范围，将所有自动指标可视化。完整演练请参阅 Studio 可观测性。

Mastra 测量的内容

Mastra 会自动发出三类指标：

• 持续时间：Agent、Workflow、Tool、模型调用和 processor 的执行时间（毫秒）。
• Token 用量：按类型（文本、缓存、音频、图像、推理）细分的输入和输出 token 数量。
• 成本估算：根据内置定价注册表估算每次模型调用的成本。

每项指标都带有 Trace 关联上下文，因此你可以从仪表板中的峰值深入查看导致它的确切 span。

有关指标名称、标签和成本字段的完整列表，请参阅自动指标参考。

自动指标的工作原理

Mastra 会自动将 Agent 运行、Workflow 步骤、Tool 调用和模型生成检测为 span。当 span 结束时，可观测性层会从中提取指标：

1. 持续时间：根据 span 的开始和结束时间戳计算。
2. Token 用量：从模型生成 span 的 usage 属性中提取。
3. 成本估算：通过按 Provider 和模型名称匹配的内置定价注册表处理每项 token 指标。

存储前，所有指标标签都会经过基数过滤器，以阻止 Trace ID 和 UUID 等已知的高基数值，从而保持存储高效。随后，指标由内部事件缓冲区批处理，并由 MastraStorageExporter 刷新到存储。

后续步骤

• 自动指标参考
• 查询指标
• Tracing 概览
• Studio 可观测性
• 可观测性概览
• MastraStorageExporter 参考