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

# Mastra platform 的可觀測性

Mastra platform 的可觀測性是一項獨立的託管產品，可讓你搜尋橫跨 Mastra 項目和部署的 Trace、日誌及指標。如果你希望毋須先部署 Studio 或設定本機儲存空間即可使用可觀測性，便可選用此產品。

在現有應用程式中加入 Mastra 時，可使用 `mastra init` 設定 platform 可觀測性；你亦可在新建立的 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
```

選擇可觀測性後，建立指令會向 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`。如果你亦希望將可觀測性事件保存至已設定的 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 可觀測性所使用的環境變數，請參閱 [Mastra platform 設定](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/configuration)。

## 查詢可觀測性數據

項目開始將 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
```

使用可觀測性指令時，CLI 會以託管的可觀測性 API 為目標，並可從項目環境推斷憑證。可用的可觀測性指令、篩選、分頁、憑證解析及直接使用 `curl` 的範例，請參閱 [`mastra api` CLI 參考資料](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)。

## 相關內容

- 📹 [Mastra 可觀測性及 Studio 工作坊](https://www.youtube.com/watch?v=dKO_a3RPra0)