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

# Studio 可觀測性

Studio 提供以下可觀測性檢視：

- **指標**：顯示彙總效能數據
- **Trace**：檢查個別請求
- **日誌**：瀏覽內部及應用程式日誌

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

## 快速開始

如需詳細指示，請參閱[可觀測性指引](https://mastra.zisheng.pro/zh-HK/docs/observability/overview)。如要快速開始，請將 `@mastra/observability` 依賴套件加入你的項目，並配合 [LibSQL](https://mastra.zisheng.pro/zh-HK/reference/storage/libsql) 及 [DuckDB](https://mastra.zisheng.pro/zh-HK/reference/vectors/duckdb) 設定本機開發環境，以同時支援 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
```

然後將以下內容加入 `src/mastra/index.ts`：

```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 平台

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

## 指標

這個儀表板可在可設定的時段範圍內（過去 24 小時至 30 日），彙總 Agent、Workflow 及 Tool 的效能。頂部一列顯示 Agent 執行總次數、模型成本、token 用量及評分器的平均表現。其下的詳細資訊卡會分別顯示各模型的使用量及成本、各 Agent 的 token 用量、token 用量隨時間的變化及估算成本、Trace 數量及完成和錯誤計數、延遲百分位數（p50 及 p95），以及評分器趨勢隨時間的變化。

詳情請參閱[指標概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/metrics/overview)。

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

## Trace

執行 Agent 或 Workflow 時，Observability 分頁會顯示 Trace，重點呈現模型呼叫、Tool 執行及 Workflow 步驟等主要 AI 操作。沿着這些 Trace 查看，即可了解數據如何流動、時間花在哪裏，以及底層正在發生甚麼事。

在 Trace 清單上方開啟 **Columns**，即可顯示或隱藏輸入、實體、持續時間、輸入 token、輸出 token、估算成本及自訂 metadata 欄。要顯示自訂 metadata，請加入 `tracingOptions.metadata` 所使用的頂層 key。Studio 會按目前的 Mastra 伺服器及 API 前綴，將選擇儲存在瀏覽器儲存空間中。

token 及估算成本欄需要支援指標的可觀測性儲存。在 **Branches** 檢視中，這些欄會保持隱藏，因為同一個 Trace 可以包含多個分支資料列。

Tracing 會過濾底層框架細節，讓 Trace 保持聚焦且易於閱讀。詳情請參閱 [Tracing 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)。

如要匯出 Trace，請在 Trace 面板標題列選擇 **Download trace JSON**。這會將整個 Trace 儲存為 `trace-<id>.json` 檔案，當中包含每個 span 及其完整輸入、輸出、metadata 和 attributes。你可以用它分享 Trace、附加至錯誤報告，或離線建立評估數據集。

## 日誌

瀏覽轉送至可觀測性儲存的 Mastra 內部日誌。日誌支援全文搜尋（涵蓋訊息內容、實體名稱及 Trace ID）、日期預設範圍（過去 24 小時至 30 日），以及按級別、實體類型和實體名稱進行多選篩選。選擇日誌後，系統會開啟詳細資料面板，顯示完整訊息、結構化數據及 metadata。如果該日誌與 Trace 相關聯，你可以直接前往該 Trace 及 span 時間軸。

設定可觀測性後，預設會啟用日誌轉送。關於級別設定、查詢範例及自訂詳情，請參閱[日誌記錄](https://mastra.zisheng.pro/zh-HK/docs/observability/logging)。

## 相關內容

- [可觀測性概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/overview)
- [指標概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/metrics/overview)
- [Tracing 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)
- [日誌記錄](https://mastra.zisheng.pro/zh-HK/docs/observability/logging)
- [Mastra 平台可觀測性](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/observability)