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

# Mastra platform 上的 Observability

Mastra platform 上的 Observability 是獨立的託管產品，可搜尋各 Mastra 專案與部署中的 Trace、記錄和指標。若你不想先部署 Studio 或設定本機儲存空間，即可使用它取得 Observability。

將 Mastra 加入現有應用程式時，可使用 `mastra init` 設定 platform Observability；新建的 Mastra 專案也能手動設定。

## 快速開始

選擇符合專案狀況的設定方式。

### 新專案

建立受管理的 Mastra 專案。出現提示時，選擇 Mastra Platform Observability 即可自動完成設定：

**npm**:

```bash
npm create mastra@latest
```

**pnpm**:

```bash
pnpm create mastra
```

**Yarn**:

```bash
yarn create mastra
```

**Bun**:

```bash
bunx create-mastra
```

選取 Observability 後，建立指令會向 Mastra Platform 驗證、佈建 platform 專案，並將認證資訊寫入專案。若略過 platform 設定或使用無提示的建立流程，請改為依照[手動設定](#manual-setup)步驟操作。

### 現有的非 Mastra 專案

若已有 Next.js 應用程式等專案，但尚未加入 Mastra，請執行 `mastra init`，並在提示時啟用 Mastra Observability：

**npm**:

```bash
npx mastra init
```

**pnpm**:

```bash
pnpm dlx mastra init
```

**Yarn**:

```bash
yarn dlx mastra init
```

**Bun**:

```bash
bun x mastra init
```

CLI 可以選取現有 platform 專案或建立新專案。

### 手動設定

在 [Mastra Platform](https://projects.mastra.ai) 建立專案，將 `MASTRA_PLATFORM_ACCESS_TOKEN` 與 `MASTRA_PROJECT_ID` 加入 `.env`，再於 Mastra 設定中註冊 `MastraPlatformExporter`。若也想將 Observability 事件保存到已設定的 Mastra Storage，請加入 `MastraStorageExporter`：

```ts
import { Mastra } from '@mastra/core/mastra'
import { Observability, MastraPlatformExporter } from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraPlatformExporter()],
      },
    },
  }),
})
```

Platform Observability 使用的環境變數請參閱 [Mastra platform 設定](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/configuration)。

## 查詢 Observability 資料

專案開始將 Trace、記錄或分數發佈至 Mastra Platform Observability 後，即可在終端機透過 Mastra CLI 或 `curl` 查詢資料。

**npm**:

```bash
npx mastra api trace list
```

**pnpm**:

```bash
pnpm dlx mastra api trace list
```

**Yarn**:

```bash
yarn dlx mastra api trace list
```

**Bun**:

```bash
bun x mastra api trace list
```

執行 Observability 指令時，CLI 會指向託管的 Observability API，並能從專案環境推斷認證資訊。可用的 Observability 指令、篩選、分頁、認證解析及直接使用 `curl` 的範例，請參閱 [`mastra api` CLI 參考](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)。

## 相關內容

- 📹 [Mastra Observability 與 Studio 工作坊](https://www.youtube.com/watch?v=dKO_a3RPra0)