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

# Studio 可觀測性

Studio 包含下列可觀測性檢視：

- **Metrics**：彙總效能資料
- **Traces**：檢查個別請求
- **Logs**：瀏覽內部與應用程式記錄

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

## 快速開始

如需詳細說明，請依照[可觀測性操作說明](https://mastra.zisheng.pro/zh-TW/docs/observability/overview)。若要快速開始，請將 `@mastra/observability` 套件加入專案，並搭配 [LibSQL](https://mastra.zisheng.pro/zh-TW/reference/storage/libsql) 與 [DuckDB](https://mastra.zisheng.pro/zh-TW/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 platform

若要跨專案與部署使用代管的 Trace、記錄和指標，請參閱 [Mastra platform 的可觀測性](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/observability)。

## 指標

此儀表板會彙整可設定時間範圍（過去 24 小時至 30 天）內的 Agent、Workflow 和 Tool 效能。最上列顯示 Agent 執行總數、模型成本、權杖用量和平均評分器效能。下方的詳細卡片會分別呈現各模型的使用量與成本、各 Agent 的權杖用量、權杖用量隨時間的變化及預估成本、含完成與錯誤數量的 Trace 數量、延遲百分位數（p50 與 p95），以及評分器隨時間的趨勢。

如需更多資訊，請參閱[指標概觀](https://mastra.zisheng.pro/zh-TW/docs/observability/metrics/overview)。

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

## Traces

執行 Agent 或 Workflow 時，Observability 分頁會顯示 Trace，醒目呈現模型呼叫、Tool 執行與 Workflow 步驟等關鍵 AI 操作。沿著這些 Trace 即可瞭解資料如何流動、時間耗費在何處，以及系統內部正在進行的作業。

在 Trace 清單上方開啟 **Columns**，可顯示或隱藏輸入、實體、持續時間、輸入權杖、輸出權杖、預估成本與自訂中繼資料欄。若要顯示自訂中繼資料，請加入 `tracingOptions.metadata` 使用的頂層鍵。Studio 會針對目前的 Mastra 伺服器與 API 前綴，將選取項目儲存在瀏覽器儲存空間中。

權杖與預估成本欄需要支援指標的可觀測性儲存區。**Branches** 檢視中會隱藏這些欄，因為多個分支資料列可能屬於同一個 Trace。

追蹤功能會篩除底層框架細節，讓 Trace 保持聚焦且易於閱讀。如需更多資訊，請參閱[追蹤概觀](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)。

若要匯出 Trace，請在 Trace 面板標頭選取 **Download trace JSON**。這會將完整 Trace 儲存為 `trace-<id>.json` 檔案，其中包含每個 span 及其完整輸入、輸出、中繼資料和屬性。你可以用它分享 Trace、附加至錯誤回報，或離線建立評估資料集。

## 記錄

瀏覽轉送至可觀測性儲存區的 Mastra 內部記錄。記錄支援全文搜尋（涵蓋訊息內容、實體名稱與 Trace ID）、日期預設範圍（過去 24 小時至 30 天），以及層級、實體類型與實體名稱的多選篩選器。選取記錄後會開啟詳細資料面板，顯示完整訊息、結構化資料與中繼資料。若記錄與 Trace 相關聯，你可以直接前往該 Trace 與 span 時間軸。

設定可觀測性後，預設會啟用記錄轉送。請參閱[記錄](https://mastra.zisheng.pro/zh-TW/docs/observability/logging)，瞭解層級設定、查詢範例與自訂方式。

## 相關內容

- [可觀測性概觀](https://mastra.zisheng.pro/zh-TW/docs/observability/overview)
- [指標概觀](https://mastra.zisheng.pro/zh-TW/docs/observability/metrics/overview)
- [追蹤概觀](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)
- [記錄](https://mastra.zisheng.pro/zh-TW/docs/observability/logging)
- [Mastra platform 可觀測性](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/observability)