> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# 可觀測性概覽

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

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

## 何時使用可觀測性

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

## 各部分如何協同運作

追蹤是整個系統的基礎。設定可觀測性後，每次 Agent 執行、Workflow 執行、Tool 呼叫和模型互動都會產生一個 [span](https://opentelemetry.io/docs/concepts/signals/traces/#spans)。span 會組織成 Trace，以階層式時間軸顯示完整的請求生命週期。

系統會自動從 Trace 衍生指標。span 結束時，Mastra 會擷取持續時間、token 數量和估算成本，毋須加入任何額外程式碼。這些指標會為 [Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/observability) 的儀表板提供資料。

日誌會自動與 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**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

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

```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 存取權](#maintaining-studio-access)，了解如何在將資料傳送至外部 Provider 時保留 Mastra Studio 存取權。

## 設定

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

### 基本設定

可觀測性設定通常包括：

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

有關目的地和 processor，請參閱[整合概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/overview)。

### 維持 Studio 存取權

加入外部 exporter 時，請保留 `MastraStorageExporter` 以供 Studio 可觀測性使用，及／或保留 `MastraPlatformExporter` 以供託管的 Mastra 平台可觀測性使用。

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

```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 的緩衝區：

```ts
await mastra.observability.flush()
```

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

### 多設定配置

當不同環境或請求類型需要不同的 exporter 或採樣行為時，請使用多個設定。使用 `configSelector` 在執行階段選擇生效的設定。

```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 採樣，請參閱[追蹤](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)。

## 儲存空間

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

### 訊號支援

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

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

有關完整 Provider 清單和支援的追蹤策略，請參閱 [Mastra Storage exporter](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/mastra-storage)。當主要儲存空間不支援可觀測性，或工作負載需要獨立擴展時，請使用複合儲存，將 `observability` domain 分開路由。

### 本機開發

本機開發時，請使用：

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

### 生產環境部署

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

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

有關後端相容性詳情和 exporter 批次處理行為，請參閱 [Mastra Storage exporter](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/mastra-storage)。

## Mastra 平台

如要跨項目和部署使用託管的 Trace、日誌和指標，請參閱 [Mastra 平台上的可觀測性](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/observability)。

## 下一步

- [追蹤](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)
- [日誌](https://mastra.zisheng.pro/zh-HK/docs/observability/logging)
- [指標](https://mastra.zisheng.pro/zh-HK/docs/observability/metrics/overview)
- [意見回饋](https://mastra.zisheng.pro/zh-HK/docs/observability/feedback)
- [整合概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/overview)
- [Mastra Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/observability)
- [自動指標參考資料](https://mastra.zisheng.pro/zh-HK/reference/observability/metrics/automatic-metrics)
- [Mastra 平台可觀測性](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/observability)