自動指標參考

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

如需設定指引，請參閱指標概覽。

Mastra 何時發出自動指標

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

影響指標是否可用的因素

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

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

如果指標不可用，請參閱疑難排解。

持續時間指標

持續時間指標會記錄以毫秒為單位的執行時間，並根據 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 指標需要用量資料。

相關內容

• 指標概覽
• 查詢指標
• Studio 可觀測性