自動指標參考

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

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

Mastra 何時產生自動指標

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

影響指標是否可用的因素

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

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

若指標無法使用，請參閱疑難排解。

持續時間指標

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

相關內容

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