可觀測性概覽

Mastra 的可觀測性系統可讓你掌握每次 Agent 執行、Workflow 步驟、Tool 呼叫與模型互動。Agent 的行為取決於模型回應、提示詞、Tool、記憶體及 Workflow 狀態，因此可觀測性能協助你從第一天起檢視執行階段的決策。它會擷取彼此互補的訊號，這些訊號會協同運作，協助你瞭解應用程式正在做什麼以及背後的原因。

• 設定：只需設定一次，即可用於 Trace、記錄、指標與回饋。
• 儲存空間：為持久保存的 Trace、記錄、指標彙總與回饋查詢選擇儲存後端。
• Tracing：將每項操作記錄為由 span 組成的階層式時間軸，並擷取輸入、輸出、token 用量與時間資訊。
• 記錄：將應用程式與 Mastra 內部的結構化記錄項目轉送至可觀測性儲存空間，並自動與 Trace 建立關聯。
• 指標：擷取 Trace 的用量與成本資料，不需要額外的檢測程式碼。
• 回饋：儲存與 Trace 和 span 連結的評分、留言、修正及其他審查訊號。
• 整合：為 Studio、託管服務或外部可觀測性 Workflow 選擇匯出器、橋接器與 span 處理器。

何時使用可觀測性

• 檢視完整的決策路徑、Tool 呼叫與模型回應，以偵錯非預期的 Agent 行為。
• 監控各 Agent、Workflow 與 Tool 的延遲，以找出瓶頸。
• 追蹤一段時間內的 token 消耗量與預估成本，以控制支出。
• 逐步追蹤執行過程，以診斷 Workflow 失敗問題。
• 比較變更提示詞或模型前後的 Agent 效能。

各個部分如何協同運作

Tracing 是整個系統的基礎。設定可觀測性後，每次 Agent 執行、Workflow 執行、Tool 呼叫與模型互動都會產生一個 span。span 會組織成 Trace，以階層式時間軸呈現完整的請求生命週期。

系統會自動從 Trace 衍生指標。span 結束時，Mastra 無須任何額外程式碼，就會擷取持續時間、token 數量與成本估算。這些指標會提供 Studio 中的儀表板所需資料。

記錄會自動與 Trace 建立關聯。在已追蹤的內容中，每次呼叫 logger.info()、logger.warn() 或 logger.error() 時，都會標記目前的 Trace 與 span ID。你可以直接從記錄項目前往產生該項目的 Trace。

回饋會記錄評分、留言與修正等人工審查訊號。回饋可與 Trace 及 span 連結，之後再透過用於指標的同一個可觀測性儲存空間進行查詢。

這些訊號共用 Trace ID、span ID、實體類型與實體名稱等關聯 ID。你可以利用這些 ID，從指標的尖峰前往其 Trace、記錄及相關回饋。

快速開始

安裝 @mastra/observability，以及支援 Trace 與指標的儲存後端：

npm

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

pnpm

pnpm add @mastra/observability @mastra/libsql @mastra/duckdb

Yarn

yarn add @mastra/observability @mastra/libsql @mastra/duckdb

Bun

bun add @mastra/observability @mastra/libsql @mastra/duckdb

接著，在 Mastra 執行個體中設定可觀測性。以下範例使用複合儲存空間，將可觀測性資料路由至 DuckDB（支援指標彙總），同時將其他所有資料保留在 LibSQL：

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
        ],
        logging: {
          enabled: true,
          level: 'info',
        },
      },
    },
  }),
})

這會啟用 Tracing、記錄轉送與指標。Mastra 也支援 Langfuse、Datadog 等外部 Tracing Provider，以及任何與 OpenTelemetry 相容的平台。若要在將資料傳送至外部 Provider 的同時保留 Mastra Studio 的存取權，請參閱保留 Studio 存取權。

設定

只需在 Mastra 執行個體上設定一次可觀測性，該設定就會套用至 Trace、記錄與指標。

基本設定

可觀測性設定通常包含：

• serviceName：附加至匯出之可觀測性資料的服務識別碼。
• exporters：Trace、記錄與衍生指標的一或多個目的地。
• spanOutputProcessors：匯出 span 前執行的轉換作業。
• logging：可觀測性儲存空間的記錄轉送設定。

如需目的地與處理器的相關資訊，請參閱整合概覽。

保留 Studio 存取權

新增外部匯出器時，請保留 MastraStorageExporter 以供 Studio 可觀測性使用，及／或保留 MastraPlatformExporter 以供託管的 Mastra 平台可觀測性使用。

以下範例僅顯示可觀測性設定。請另行設定儲存空間。

src/mastra/observability.ts

import { Observability, MastraStorageExporter, MastraPlatformExporter } from '@mastra/observability'
import { ArizeExporter } from '@mastra/arize'

export const observability = new Observability({
  configs: {
    production: {
      serviceName: 'my-service',
      exporters: [
        new ArizeExporter({
          endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
          apiKey: process.env.PHOENIX_API_KEY,
        }),
        new MastraStorageExporter(),
        new MastraPlatformExporter(),
      ],
    },
  },
})

在無伺服器環境中清空緩衝區

在無伺服器環境中，請在執行階段暫停或結束前，清空可觀測性匯出器的緩衝區：

await mastra.observability.flush()

在無伺服器環境中，請使用外部儲存空間，而不是本機檔案儲存空間。如需選擇與路由儲存空間的相關資訊，請參閱儲存空間。

多重設定

當不同環境或請求類型需要不同的匯出器或取樣行為時，請使用多組設定。在執行階段使用 configSelector 選取作用中的設定。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LangfuseExporter } from '@mastra/langfuse'

const storageExporter = new MastraStorageExporter()
const langfuseExporter = new LangfuseExporter()

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      development: {
        serviceName: 'my-service-dev',
        exporters: [storageExporter],
      },
      production: {
        serviceName: 'my-service-prod',
        exporters: [storageExporter, langfuseExporter],
      },
    },
    configSelector: () => process.env.NODE_ENV || 'development',
  }),
})

如需 Trace 取樣的相關資訊，請參閱 Tracing。

儲存空間

儲存空間會決定要持久保存哪些可觀測性訊號、可使用哪些查詢，以及指標彙總是否能運作。請使用專用的可觀測性儲存空間，而不是主要的應用程式儲存空間。

訊號支援

儲存空間的支援範圍取決於訊號與工作負載。MastraStorageExporter 可將 Trace 持久保存至 ClickHouse、PostgreSQL、MSSQL、MongoDB 與 LibSQL。指標則需要具備分析能力的儲存空間：

• DuckDB：建議用於本機測試與開發。
• ClickHouse：建議用於高流量的正式環境可觀測性。
• PostgresStoreVNext：啟用可觀測性網域時支援指標。請一律提供時間範圍，以免掃描完整分割區。
• Mastra 平台：使用 MastraPlatformExporter 取得託管的可觀測性，而無須自行管理後端。

如需完整的 Provider 清單與支援的 Tracing 策略，請參閱 Mastra Storage 匯出器。當主要儲存空間不支援可觀測性，或工作負載需要獨立擴充時，請使用複合儲存空間，將 observability 網域分開路由。

本機開發

本機開發時，請使用：

• LibSQLStore 作為主要的應用程式儲存空間
• DuckDBStore 用於 observability 網域
• MastraStorageExporter 用於本機 Studio 存取

正式環境部署

可觀測性流量的寫入量通常高於應用程式其餘部分。正式環境中：

• 若將可觀測性保留在自己的儲存空間中，請將 MastraStorageExporter 與 ClickHouse 搭配使用於 observability 網域。
• 使用 MastraPlatformExporter 取得託管的 Mastra 平台可觀測性，而不是自行管理後端。
• 當可觀測性需要與主要應用程式資料使用不同的後端或擴充原則時，請使用複合儲存空間。

如需後端相容性與匯出器批次處理行為的詳細資訊，請參閱 Mastra Storage 匯出器。

Mastra 平台

如需跨專案與部署的託管 Trace、記錄與指標，請參閱 Mastra 平台上的可觀測性。

後續步驟

• Tracing
• 記錄
• 指標
• 回饋
• 整合概覽
• Mastra Studio
• 自動指標參考文件
• Mastra 平台可觀測性