跳至主要內容

Studio 可觀測性

Studio 包含下列可觀測性檢視：

  • Metrics：彙總效能資料
  • Traces：檢查個別請求
  • Logs：瀏覽內部與應用程式記錄

所有檢視都必須設定可觀測性儲存後端。

快速開始
「快速開始」的直接連結

如需詳細說明，請依照可觀測性操作說明。若要快速開始，請將 @mastra/observability 套件加入專案，並搭配 LibSQL 與 DuckDB 設定支援 Trace 與指標的本機開發環境。

npm install @mastra/observability @mastra/libsql @mastra/duckdb

接著將以下內容加入 src/mastra/index.ts：

src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { MastraCompositeStore } from '@mastra/core/storage'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      observability: await new DuckDBStore().getStore('observability'),
    },
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (if MASTRA_PLATFORM_ACCESS_TOKEN is set)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
        ],
      },
    },
  }),
})

Mastra platform
「Mastra platform」的直接連結

若要跨專案與部署使用代管的 Trace、記錄和指標，請參閱 Mastra platform 的可觀測性。

指標
「指標」的直接連結

此儀表板會彙整可設定時間範圍（過去 24 小時至 30 天）內的 Agent、Workflow 和 Tool 效能。最上列顯示 Agent 執行總數、模型成本、權杖用量和平均評分器效能。下方的詳細卡片會分別呈現各模型的使用量與成本、各 Agent 的權杖用量、權杖用量隨時間的變化及預估成本、含完成與錯誤數量的 Trace 數量、延遲百分位數（p50 與 p95），以及評分器隨時間的趨勢。

如需更多資訊，請參閱指標概觀。

備註

指標需要獨立的 OLAP 儲存區來保存可觀測性資料。PostgreSQL、LibSQL 等關聯式資料庫不支援指標。記憶體內儲存區會在重新啟動後重設。

Traces
「Traces」的直接連結

執行 Agent 或 Workflow 時，Observability 分頁會顯示 Trace，醒目呈現模型呼叫、Tool 執行與 Workflow 步驟等關鍵 AI 操作。沿著這些 Trace 即可瞭解資料如何流動、時間耗費在何處，以及系統內部正在進行的作業。

在 Trace 清單上方開啟 Columns，可顯示或隱藏輸入、實體、持續時間、輸入權杖、輸出權杖、預估成本與自訂中繼資料欄。若要顯示自訂中繼資料，請加入 tracingOptions.metadata 使用的頂層鍵。Studio 會針對目前的 Mastra 伺服器與 API 前綴，將選取項目儲存在瀏覽器儲存空間中。

權杖與預估成本欄需要支援指標的可觀測性儲存區。Branches 檢視中會隱藏這些欄，因為多個分支資料列可能屬於同一個 Trace。

追蹤功能會篩除底層框架細節，讓 Trace 保持聚焦且易於閱讀。如需更多資訊，請參閱追蹤概觀。

若要匯出 Trace，請在 Trace 面板標頭選取 Download trace JSON。這會將完整 Trace 儲存為 trace-<id>.json 檔案，其中包含每個 span 及其完整輸入、輸出、中繼資料和屬性。你可以用它分享 Trace、附加至錯誤回報，或離線建立評估資料集。

記錄
「記錄」的直接連結

瀏覽轉送至可觀測性儲存區的 Mastra 內部記錄。記錄支援全文搜尋（涵蓋訊息內容、實體名稱與 Trace ID）、日期預設範圍（過去 24 小時至 30 天），以及層級、實體類型與實體名稱的多選篩選器。選取記錄後會開啟詳細資料面板，顯示完整訊息、結構化資料與中繼資料。若記錄與 Trace 相關聯，你可以直接前往該 Trace 與 span 時間軸。

設定可觀測性後，預設會啟用記錄轉送。請參閱記錄，瞭解層級設定、查詢範例與自訂方式。

On this page