可觀測性概覽

Mastra 的可觀測性系統讓你全面掌握每次 Agent 執行、Workflow 步驟、Tool 呼叫和模型互動。Agent 的行為取決於模型回應、提示、Tool、記憶和 Workflow 狀態，因此可觀測性可助你從第一天起檢視執行階段的決策。系統會擷取相輔相成的訊號，協助你了解應用程式正在做甚麼以及箇中原因。

• 設定：一次設定可觀測性，以處理 Trace、日誌、指標和意見回饋。
• 儲存空間：為持久保存的 Trace、日誌、指標彙整和意見回饋查詢選擇儲存後端。
• 追蹤：將每項操作記錄為由 span 組成的階層式時間軸，擷取輸入、輸出、token 用量和時間資料。
• 日誌：將應用程式和 Mastra 內部的結構化日誌項目轉送至可觀測性儲存空間，並自動與 Trace 建立關聯。
• 指標：從 Trace 擷取用量和成本資料，毋須額外加入偵測程式碼。
• 意見回饋：儲存與 Trace 和 span 連結的評分、留言、修正和其他審查訊號。
• 整合：為 Studio、託管或外部可觀測性 Workflow 選擇 exporter、bridge 和 span processor。

何時使用可觀測性

• 檢視完整的決策路徑、Tool 呼叫和模型回應，為非預期的 Agent 行為除錯。
• 監察各 Agent、Workflow 和 Tool 的延遲，以找出樽頸。
• 持續追蹤 token 用量和估算成本，以控制開支。
• 追蹤每個步驟的執行情況，診斷 Workflow 失敗原因。
• 比較變更提示或模型前後的 Agent 效能。

各部分如何協同運作

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

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

日誌會自動與 Trace 建立關聯。在追蹤情境中，每次呼叫 logger.info()、logger.warn() 或 logger.error()，系統都會以目前的 trace ID 和 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',
        },
      },
    },
  }),
})

這會啟用追蹤、日誌轉送和指標。Mastra 亦支援 Langfuse、Datadog 和任何與 OpenTelemetry 相容的平台等外部追蹤 Provider。請參閱維持 Studio 存取權，了解如何在將資料傳送至外部 Provider 時保留 Mastra Studio 存取權。

設定

可觀測性只需在 Mastra 執行個體上設定一次，並會套用至 Trace、日誌和指標。

基本設定

可觀測性設定通常包括：

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

有關目的地和 processor，請參閱整合概覽。

維持 Studio 存取權

加入外部 exporter 時，請保留 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(),
      ],
    },
  },
})

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

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

await mastra.observability.flush()

在無伺服器環境中，請使用外部儲存空間，而非本機檔案儲存空間。有關儲存空間選擇和路由，請參閱儲存空間。

多設定配置

當不同環境或請求類型需要不同的 exporter 或採樣行為時，請使用多個設定。使用 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 採樣，請參閱追蹤。

儲存空間

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

訊號支援

儲存空間支援視乎訊號和工作負載而定。MastraStorageExporter 可將 Trace 持久保存至 ClickHouse、PostgreSQL、MSSQL、MongoDB 和 LibSQL。指標需要具備分析能力的儲存空間：

• DuckDB：建議用於本機測試和開發。
• ClickHouse：建議用於高流量的生產環境可觀測性。
• PostgresStoreVNext：啟用 observability domain 時支援指標。請務必提供時間範圍，以免完整掃描分區。
• Mastra 平台：使用 MastraPlatformExporter，毋須自行管理後端即可使用託管的可觀測性。

有關完整 Provider 清單和支援的追蹤策略，請參閱 Mastra Storage exporter。當主要儲存空間不支援可觀測性，或工作負載需要獨立擴展時，請使用複合儲存，將 observability domain 分開路由。

本機開發

本機開發時，請使用：

• LibSQLStore 作為應用程式的主要儲存空間
• DuckDBStore 作為 observability domain 的儲存空間
• MastraStorageExporter 以便在本機存取 Studio

生產環境部署

可觀測性流量的寫入量通常較應用程式其他部分為高。在生產環境中：

• 如將可觀測性資料保留在自有儲存空間，請使用配合 ClickHouse 的 MastraStorageExporter 作為 observability domain 的儲存方案。
• 使用 MastraPlatformExporter 取得託管的 Mastra 平台可觀測性，毋須自行管理後端。
• 當可觀測性需要與主要應用程式資料不同的後端或擴展策略時，請使用複合儲存。

有關後端相容性詳情和 exporter 批次處理行為，請參閱 Mastra Storage exporter。

Mastra 平台

如要跨項目和部署使用託管的 Trace、日誌和指標，請參閱 Mastra 平台上的可觀測性。

下一步

• 追蹤
• 日誌
• 指標
• 意見回饋
• 整合概覽
• Mastra Studio
• 自動指標參考資料
• Mastra 平台可觀測性