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

# 自動指標參考

Mastra 會自動從 Trace 執行中擷取效能與用量指標。本頁提供 Mastra 所產生每個指標名稱、標籤及 context 欄位的完整參考。

如需設定說明，請參閱[指標概覽](https://mastra.zisheng.pro/zh-TW/docs/observability/metrics/overview)。

## Mastra 何時產生自動指標

Span 結束時會從中擷取指標。可觀測性層會檢查每個已完成的 span、計算持續時間，並針對模型生成 span 讀取 token 用量資料。不需要手動檢測。

### 影響指標是否可用的因素

指標會在下列情況寫入儲存空間：

1. 已將 `MastraStorageExporter` 設定為 exporter。
2. 儲存後端支援指標（ClickHouse、DuckDB，或已啟用 observability domain 的 Postgres v-next）。

若指標無法使用，請參閱[疑難排解](#troubleshooting)。

## 持續時間指標

持續時間指標記錄執行時間（以毫秒為單位），並根據 span 的開始與結束時間戳記計算。每個持續時間指標都包含 `status` 標籤，其值會依 span 狀態設為 `ok` 或 `error`。

| 指標名稱                           | 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`                                    | processor 執行的執行時間                          |

## 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。

## 費用相關 context

### 何時附加費用 context

當 Provider 回報每個已完成模型步驟的有效費用，或內建定價登錄中有符合該 Provider 與模型的項目時，token 指標就會附加費用 context。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`  | 其他定價 context，包括級距資訊、錯誤詳細資料，以及 Provider 回報費用的來源與範圍 |

## 與 trace 的關聯

### 指標與 span 及 trace context 的關係

每個指標都會攜帶產生該指標之 span 的 `CorrelationContext` 快照。此 context 會與指標值一同儲存，並將指標連結到確切的 span 與 trace。

關聯欄位分為以下類別：

**Trace 關聯**

- `traceId`：trace 識別碼
- `spanId`：span 識別碼
- `tags`：來自 span 的標籤

**實體階層**

- `entityType`, `entityId`, `entityName`：產生指標的實體（例如 Agent、Workflow）
- `parentEntityType`, `parentEntityId`, `parentEntityName`：父實體
- `rootEntityType`, `rootEntityId`, `rootEntityName`：呼叫鏈中的根實體

**身分識別**

- `userId`, `organizationId`, `resourceId`：來自請求的身分 context
- `runId`, `sessionId`, `threadId`, `requestId`：關聯 ID

**部署**

- `environment`：部署環境（例如 `production`、`staging`）
- `source`：來源識別碼
- `serviceName`：來自可觀測性設定的服務名稱
- `experimentId`：實驗識別碼（若適用）

### 關聯如何協助偵錯

當您在 Metrics dashboard 發現延遲或 token 用量突然增加時，關聯 context 可讓您直接深入查看產生該指標的 trace，並從中檢查各個 span。根本原因可能是緩慢的 Tool 呼叫或過大的提示，也可能是非預期的錯誤。

## 疑難排解

### 沒有可用的指標

- **已設定可觀測性**：確認您的 `Mastra` 執行個體具有 `observability` 設定，且至少包含一個 exporter。
- **存在 `MastraStorageExporter` 或 `MastraPlatformExporter`**：其他 exporter（Datadog、Langfuse 等）不會在 Mastra 中呈現指標。本機 Studio dashboard 需要 `MastraStorageExporter`，而若要在 Mastra platform 檢視指標，則需要 `MastraPlatformExporter`。
- **儲存空間支援指標**：指標需要具備分析能力的儲存區（ClickHouse、DuckDB，或已啟用 observability domain 的 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 是模型生成**：只有 `MODEL_GENERATION` span 會產生 token 指標。
- **Provider 回報用量**：模型 Provider 必須在回應中包含 `usage` 資料。產生 token 指標需要用量資料。

## 相關內容

- [指標概覽](https://mastra.zisheng.pro/zh-TW/docs/observability/metrics/overview)
- [查詢指標](https://mastra.zisheng.pro/zh-TW/docs/observability/metrics/querying)
- [Studio 可觀測性](https://mastra.zisheng.pro/zh-TW/docs/studio/observability)