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

# 指标概览

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

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

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

> **备注:** 指标需要支持分析的可观测性存储。大多数关系型数据库（LibSQL、MSSQL）不支持指标。内存存储会在重启时重置。
>
> 本地开发请通过 `@mastra/duckdb` 使用 [DuckDB](https://duckdb.org/)。生产环境请通过 `@mastra/clickhouse` 使用 [ClickHouse](https://clickhouse.com/)。启用 observability domain 的 `PostgresStoreVNext` 也支持指标，但请始终提供时间范围，避免扫描完整分区。
>
> Google Cloud Spanner 支持指标，但不建议用于高负载指标工作负载。由于指标具有高写入量和高扫描量，Spanner adapter 默认禁用指标。仅对轻量工作负载设置 `disableMetrics: false`，或者将指标路由到 OLAP 存储。

## 何时使用指标

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

## 开始使用

安装所需软件包：

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

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

```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 可观测性](https://mastra.zisheng.pro/docs/studio/observability)。

## Mastra 测量的内容

Mastra 会自动发出三类指标：

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

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

有关指标名称、标签和成本字段的完整列表，请参阅[自动指标参考](https://mastra.zisheng.pro/reference/observability/metrics/automatic-metrics)。

## 自动指标的工作原理

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

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

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

## 后续步骤

- [自动指标参考](https://mastra.zisheng.pro/reference/observability/metrics/automatic-metrics)
- [查询指标](https://mastra.zisheng.pro/docs/observability/metrics/querying)
- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [Studio 可观测性](https://mastra.zisheng.pro/docs/studio/observability)
- [可观测性概览](https://mastra.zisheng.pro/docs/observability/overview)
- [MastraStorageExporter 参考](https://mastra.zisheng.pro/docs/observability/integrations/exporters/mastra-storage)