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

# 可觀測性概覽

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

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

## 何時使用可觀測性

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

## 各個部分如何協同運作

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

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

記錄會自動與 Trace 建立關聯。在已追蹤的內容中，每次呼叫 `logger.info()`、`logger.warn()` 或 `logger.error()` 時，都會標記目前的 Trace 與 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',
        },
      },
    },
  }),
})
```

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

## 設定

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

### 基本設定

可觀測性設定通常包含：

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

如需目的地與處理器的相關資訊，請參閱[整合概覽](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/overview)。

### 保留 Studio 存取權

新增外部匯出器時，請保留 `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(),
      ],
    },
  },
})
```

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

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

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

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

### 多重設定

當不同環境或請求類型需要不同的匯出器或取樣行為時，請使用多組設定。在執行階段使用 `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 取樣的相關資訊，請參閱 [Tracing](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)。

## 儲存空間

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

### 訊號支援

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

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

如需完整的 Provider 清單與支援的 Tracing 策略，請參閱 [Mastra Storage 匯出器](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/mastra-storage)。當主要儲存空間不支援可觀測性，或工作負載需要獨立擴充時，請使用複合儲存空間，將 `observability` 網域分開路由。

### 本機開發

本機開發時，請使用：

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

### 正式環境部署

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

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

如需後端相容性與匯出器批次處理行為的詳細資訊，請參閱 [Mastra Storage 匯出器](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/mastra-storage)。

## Mastra 平台

如需跨專案與部署的託管 Trace、記錄與指標，請參閱 [Mastra 平台上的可觀測性](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/observability)。

## 後續步驟

- [Tracing](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)
- [記錄](https://mastra.zisheng.pro/zh-TW/docs/observability/logging)
- [指標](https://mastra.zisheng.pro/zh-TW/docs/observability/metrics/overview)
- [回饋](https://mastra.zisheng.pro/zh-TW/docs/observability/feedback)
- [整合概覽](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/overview)
- [Mastra Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/observability)
- [自動指標參考文件](https://mastra.zisheng.pro/zh-TW/reference/observability/metrics/automatic-metrics)
- [Mastra 平台可觀測性](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/observability)