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

# 自動指標參考

Mastra 會自動從已追蹤的執行中擷取效能及使用量指標。本頁完整列出 Mastra 發出的每個指標名稱、標籤及上下文欄位。

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

## Mastra 何時發出自動指標

span 結束時，系統會從中擷取指標。可觀測性層會檢查每個已完成的 span、計算持續時間，並讀取模型生成 span 的 token 使用量資料，毋須手動加入監測程式碼。

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

指標會在符合以下條件時寫入儲存空間：

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

如果指標不可用，請參閱[疑難排解](#troubleshooting)。

## 持續時間指標

持續時間指標會記錄以毫秒為單位的執行時間，並根據 span 的開始及結束時間戳計算。每個持續時間指標均包括一個由 span 狀態衍生的 `status` 標籤，其值為 `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-series） |
| `mastra_model_output_audio_tokens`     | 模型輸出中的音訊 token                   |
| `mastra_model_output_image_tokens`     | 輸出圖像 token                       |

### Provider 回報的詳細 token 類別

只有 Provider 回報相關資料時，系統才會發出詳細分類指標（`total_input` 及 `total_output` 除外）。如某類別的 token 數目為零，系統會略過該 span 的相應指標。不同 Provider 回報的詳細程度各異，例如並非所有 Provider 都會回報快取或音訊 token。

## 成本相關上下文

### 何時附加成本上下文

當 Provider 為每個已完成的模型步驟回報有效成本，或內置定價 registry 中有與該 Provider 及模型相符的項目時，系統便會在 token 指標附加成本上下文。Mastra 會將 Provider 回報的每步成本加總為單次查詢總額。如任何已完成步驟沒有有效的回報成本，Mastra 會改用定價 registry，而不會回報不完整的總額。如兩種來源均不可用，系統仍會發出 token 指標，但不包含成本欄位。

呼叫者提供的 `costContext` 優先於 Provider 回報的成本及定價 registry 估算。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`  | 額外定價情境，包括級別資料、錯誤詳情，以及 Provider 報告成本的來源和範圍     |

## 與 Trace 的關聯

### 指標如何與 span 及 Trace 上下文關聯

每個指標均帶有產生該指標之 span 的 `CorrelationContext` 快照。此上下文會連同指標值儲存，將指標連結至確切的 span 及 Trace。

關聯欄位分為以下類別：

**Trace 關聯**

- `traceId`：Trace 識別碼
- `spanId`：span 識別碼
- `tags`：span 的標籤

**實體階層**

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

**身分**

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

**部署**

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

### 關聯如何協助偵錯

當你在 Metrics 儀表板發現延遲或 token 使用量急升時，可透過關聯上下文直接深入查看產生該指標的 Trace，然後檢查個別 span。根本原因可能是緩慢的 Tool 呼叫、過長的提示，亦可能是非預期錯誤。

## 疑難排解

### 沒有可用的指標

- **已設定可觀測性**：確認你的 `Mastra` instance 設有 `observability` 設定，並包含至少一個 exporter。
- **已加入 `MastraStorageExporter` 或 `MastraPlatformExporter`**：其他 exporter（Datadog、Langfuse 等）不會在 Mastra 顯示指標。本機 Studio 儀表板需要 `MastraStorageExporter`，而在 Mastra platform 查看指標則需要 `MastraPlatformExporter`。
- **儲存空間支援指標**：指標需要支援分析的儲存空間（ClickHouse、DuckDB，或已啟用可觀測性網域的 Postgres v-next）。其他以資料列為本的資料庫（LibSQL、MSSQL）及文件儲存空間（MongoDB）不支援指標。
- **抽樣並非 0%**：如果抽樣概率是 `0` 或策略是 `never`，所有 span 都不會執行任何操作，亦不會擷取任何指標。

### 缺少持續時間指標

- **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-HK/docs/observability/metrics/overview)
- [查詢指標](https://mastra.zisheng.pro/zh-HK/docs/observability/metrics/querying)
- [Studio 可觀測性](https://mastra.zisheng.pro/zh-HK/docs/studio/observability)