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

# 查詢指標

Mastra 透過三種介面提供相同的五種 OLAP 查詢（`getMetricAggregate`、`getMetricBreakdown`、`getMetricTimeSeries`、`getMetricPercentiles` 及探索輔助函式）：行程內儲存存取器、執行階段 HTTP API，以及 `mastra api metric` CLI。三者接受相同並經 Zod 驗證的輸入結構，因此你可以由一次性的 CLI 調查轉移至程式化儀表板 Tool，毋須重新學習 API。

**供 AI Agent 使用：** 執行 `npx mastra api metric aggregate '{"name":"mastra_agent_duration_ms","aggregation":"avg"}'`，即可直接查詢 Agent 的平均延遲，毋須編寫臨時腳本。查詢本機指標需要一個正在運行的 Mastra 伺服器，並配備支援 OLAP 的可觀測性儲存；你可以使用 `npx mastra dev` 啟動本機伺服器，或透過 `--url` 傳入可連線伺服器的基礎 URL。建立其他查詢前，請先執行 `npx mastra api metric aggregate --schema`。使用 `npx skills add mastra-ai/skills --skill mastra` 安裝 Mastra Skill，即可取得完整的 API CLI 探索、目標設定、結構描述、驗證及錯誤處理指引。

## 適用情況

- 在 Studio 旁建立自訂儀表板或 KPI 資訊方塊。
- 建立排程警報，在 token 成本或延遲超出臨界值時觸發。
- 為 Agent 提供可讀取自身效能指標並在對話中加以解釋的 Tool。
- 從終端機使用 `mastra api metric ...` 進行一次性調查。

如要設定可觀測性儲存本身，請參閱[指標概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/metrics/overview)。如要查看可供查詢的指標名稱清單，請參閱[自動指標參考](https://mastra.zisheng.pro/zh-HK/reference/observability/metrics/automatic-metrics)。

> **備註:** 指標查詢由可觀測性網域提供，而該網域需要支援 OLAP 的儲存（本機使用 DuckDB，正式環境使用 ClickHouse）。設定方法請參閱[指標概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/metrics/overview)。如果尚未設定可觀測性儲存，`getStore('observability')` 會傳回 `null`。

## 介面

### 行程內

在 Tool、伺服器路由或 Workflow 步驟中，從 Mastra 儲存取得可觀測性儲存：

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const agentLatencyTool = createTool({
  id: 'agentLatency',
  description: 'Average agent latency over the last hour.',
  inputSchema: z.object({}),
  execute: async (_input, context) => {
    const observability = await context.mastra!.getStorage()!.getStore('observability')
    if (!observability) {
      throw new Error('Observability domain is not configured (requires DuckDB or ClickHouse)')
    }

    const result = await observability.getMetricAggregate({
      name: ['mastra_agent_duration_ms'],
      aggregation: 'avg',
      filters: {
        timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
      },
    })

    return { averageMs: result.value }
  },
})
```

當已設定的後端不支援 OLAP 查詢時，`getStore('observability')` 會傳回 `null`。

### HTTP

`mastra dev` 伺服器（以及任何已部署的 Mastra 執行階段）會在 `/api/observability/metrics/*` 下提供相同的查詢。彙總、細分、時間序列及百分位數端點會透過 `POST` 接收 JSON 內文。探索端點則使用帶有查詢參數的 `GET`。

```bash
curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
  -H "content-type: application/json" \
  -d '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}'
```

可用路由：

- `POST /api/observability/metrics/aggregate`
- `POST /api/observability/metrics/breakdown`
- `POST /api/observability/metrics/timeseries`
- `POST /api/observability/metrics/percentiles`
- `GET /api/observability/metrics`（原始資料列，已分頁）
- `GET /api/observability/discovery/metric-names`
- `GET /api/observability/discovery/metric-label-keys`
- `GET /api/observability/discovery/metric-label-values`

`@mastra/client-js` SDK 會將相同的路由封裝為 `mastraClient.getMetricAggregate(...)`、`getMetricBreakdown(...)` 等方法。

### CLI

`mastra api metric ...` 會以單一 JSON 參數呼叫相同的端點，因此 Agent 或 shell 腳本毋須編寫任何程式碼即可擷取指標：

```bash
mastra api metric aggregate \
  '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}' \
  --url http://localhost:4111
```

CLI 預設以託管的 Mastra 可觀測性服務（`https://observability.mastra.ai`）為目標。傳入 `--url http://localhost:4111` 即可查詢本機 `mastra dev` 伺服器。如要查看完整命令清單，請參閱 [`mastra api metric aggregate`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra) 及其附近的條目。

## 查詢

### `getMetricAggregate`

傳回單一純量，是建立 KPI 卡片的基礎。

輸入：

- `name`：包含一個或多個指標名稱的陣列。
- `aggregation`：可選 `'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'last'` 其中之一。
- `filters`：可選的[篩選物件](#filtering)。
- `comparePeriod`：可選 `'previous_period' | 'previous_day' | 'previous_week'`，用於比較不同期間。

回應：

- `value`、`previousValue`、`changePercent`。
- token 指標的 `estimatedCost`、`costUnit`、`previousEstimatedCost`、`costChangePercent`。

```typescript
const observability = await mastra.getStorage()!.getStore('observability')

const cost = await observability!.getMetricAggregate({
  name: ['mastra_model_total_input_tokens', 'mastra_model_total_output_tokens'],
  aggregation: 'sum',
  comparePeriod: 'previous_day',
})

console.log(cost.value, cost.estimatedCost, cost.costUnit, cost.changePercent)
```

### `getMetricBreakdown`

按照一個或多個維度將資料列分組，並彙總每個群組，是建立前 N 名表格（例如「按 Agent 劃分的 token」）的基礎。

輸入：

- `name`：指標名稱陣列。
- `groupBy`：用於分組的欄位陣列（例如 `['entityName']`）。
- `aggregation`：與上述相同的列舉值。
- `limit`：伺服器端的前 K 名上限。使用高基數 `groupBy` 時必須提供。
- `orderDirection`：`'ASC' | 'DESC'`（預設為 `DESC`）。
- `filters`：可選。

回應：`groups[]`，每項均包含 `dimensions`（由群組鍵對應至值的記錄）、`value` 及 `estimatedCost`。

```typescript
const byAgent = await observability!.getMetricBreakdown({
  name: ['mastra_model_total_input_tokens'],
  groupBy: ['entityName'],
  aggregation: 'sum',
  limit: 10,
  orderDirection: 'DESC',
})
```

### `getMetricTimeSeries`

以固定間隔將值分桶，是建立折線圖及棒形圖的基礎。

輸入：

- `name`：指標名稱陣列。
- `interval`：可選 `'1m' | '5m' | '15m' | '1h' | '1d'` 其中之一。
- `aggregation`：相同的列舉值。
- `groupBy`：可選。省略時，多個指標名稱會合計為一個序列。如要將各指標分開，請為每個指標各呼叫一次。
- `filters`：可選。

回應：`series[]`，每項均包含 `name`、`costUnit` 及 `points[]`，當中的資料點結構為 `{ timestamp, value, estimatedCost }`。

```typescript
const inputTokens = await observability!.getMetricTimeSeries({
  name: ['mastra_model_total_input_tokens'],
  aggregation: 'sum',
  interval: '1h',
  filters: {
    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
  },
})
```

### `getMetricPercentiles`

傳回按時間分桶的百分位數值，是建立延遲圖表的基礎。

輸入：

- `name`：單一指標名稱（字串，而非陣列）。
- `percentiles`：介乎 `0` 至 `1` 之間的數字陣列，例如 `[0.5, 0.95, 0.99]`。
- `interval`：與 `getMetricTimeSeries` 相同的列舉值。
- `filters`：可選。

回應：`series[]`，每項均包含 `percentile` 及 `points[]`，當中的資料點結構為 `{ timestamp, value }`。

```typescript
const latency = await observability!.getMetricPercentiles({
  name: 'mastra_agent_duration_ms',
  percentiles: [0.5, 0.95],
  interval: '1h',
})
```

### 探索

使用這些端點填入下拉式選單，或為 Agent 提供可供篩選的值清單。所有探索路由均使用 `GET`，並位於 `/api/observability/discovery/` 下。

**指標專用**（亦以 `mastra api metric` 子命令提供）：

| 方法                     | 參數                                          | 路徑後綴                  | CLI                              |
| ---------------------- | ------------------------------------------- | --------------------- | -------------------------------- |
| `getMetricNames`       | `{ prefix?, limit? }`                       | `metric-names`        | `mastra api metric names`        |
| `getMetricLabelKeys`   | `{ metricName }`                            | `metric-label-keys`   | `mastra api metric label-keys`   |
| `getMetricLabelValues` | `{ metricName, labelKey, prefix?, limit? }` | `metric-label-values` | `mastra api metric label-values` |

**與 Trace 及日誌共用**（僅限 HTTP，沒有專用 CLI 子命令）：

| 方法                | 參數                | 路徑後綴            |
| ----------------- | ----------------- | --------------- |
| `getEntityTypes`  | `{}`              | `entity-types`  |
| `getEntityNames`  | `{ entityType? }` | `entity-names`  |
| `getServiceNames` | `{}`              | `service-names` |
| `getEnvironments` | `{}`              | `environments`  |
| `getTags`         | `{ entityType? }` | `tags`          |

## 篩選

每種查詢都接受相同的 `filters` 物件。最實用的欄位包括：

- `name`：限制為指定的指標名稱。（對於彙總／細分／時間序列，頂層 `name` 已可達到此目的。如要在單一查詢中混合多個指標，請使用 `filters.name`。）
- `timestamp`：`{ start, end, startExclusive, endExclusive }`。兩個界限均為可選。省略 `end` 即表示「直至現在」。
- `provider`、`model`、`costUnit`：用於 token 及成本指標。
- `labels`：與指標標籤進行精確鍵值配對，例如持續時間指標可使用 `{ status: 'error' }`。
- 關聯欄位：`entityType`、`entityName`、`parentEntityName`、`rootEntityName`、`userId`、`organizationId`、`resourceId`、`runId`、`sessionId`、`threadId`、`requestId`、`executionSource`、`environment`、`serviceName`、`experimentId`、`tags`。

相同的 `filters` 結構適用於全部三種介面：

```typescript
// In-process
await observability!.getMetricAggregate({
  name: ['mastra_tool_duration_ms'],
  aggregation: 'avg',
  filters: { entityName: 'weatherTool', labels: { status: 'error' } },
})
```

```bash
# CLI
mastra api metric aggregate \
  '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}' \
  --url http://localhost:4111
```

```bash
# HTTP
curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
  -H "content-type: application/json" \
  -d '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}'
```

### 一律提供時間範圍

`filters.timestamp` 屬於可選項目，但對於任何在正式環境儲存上運行的查詢，你都應將其視為必要項目。可觀測性資料表通常會按事件時間分割（TimescaleDB 則會分塊）。提供 `timestamp.start`（最好亦提供 `end`）後，後端可將查詢範圍縮減至與該範圍重疊的分割區，通常只有一至兩個。如果不提供時間範圍，規劃器便必須掃描每個分割區；若保留期為一年，可能涉及數百個區段，這亦是採用 Postgres 後端的儲存出現 OLAP 查詢緩慢的最常見原因。

臨時查詢的穩妥預設值是過去 24 小時；警報及儀表板則應配合其實際評估時段：

```typescript
await observability!.getMetricAggregate({
  name: ['mastra_agent_duration_ms'],
  aggregation: 'p95',
  filters: {
    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
  },
})
```

這項指引適用於所有後端（ClickHouse、Postgres v-next、DuckDB），但對 Postgres v-next 最為重要，因為每缺少一個時間界限，都會直接增加一次分割區掃描。

## 範例：建立自訂 KPI 資訊方塊

以下 Tool 會傳回過去一小時的輸入 token 數量及估算成本。Agent 或儀表板可透過 `structuredContent` 呼叫此 Tool，毋須重新實作查詢。

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const tokenKpiTool = createTool({
  id: 'tokenKpi',
  description: 'Returns input-token volume and estimated cost for the last hour.',
  inputSchema: z.object({}),
  outputSchema: z.object({
    inputTokens: z.number().nullable(),
    estimatedCost: z.number().nullable(),
    costUnit: z.string().nullable(),
    changePercent: z.number().nullable(),
  }),
  execute: async (_input, context) => {
    const observability = await context.mastra!.getStorage()!.getStore('observability')
    if (!observability) {
      throw new Error('Observability domain is not configured (requires DuckDB or ClickHouse)')
    }

    const result = await observability.getMetricAggregate({
      name: ['mastra_model_total_input_tokens'],
      aggregation: 'sum',
      filters: {
        timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
      },
      comparePeriod: 'previous_period',
    })

    return {
      inputTokens: result.value,
      estimatedCost: result.estimatedCost ?? null,
      costUnit: result.costUnit ?? null,
      changePercent: result.changePercent ?? null,
    }
  },
})
```

## 相關內容

- [指標概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/metrics/overview)
- [自動指標參考](https://mastra.zisheng.pro/zh-HK/reference/observability/metrics/automatic-metrics)
- [CLI：`mastra api metric ...`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)
- [Studio 可觀測性](https://mastra.zisheng.pro/zh-HK/docs/studio/observability)