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

# Mastra platform 上的 Observability

Mastra platform 上的 Observability 是一款独立托管产品，用于跨 Mastra 项目和部署搜索 Trace、日志与指标。如果需要 Observability，但不想先部署 Studio 或设置本地 Storage，请使用它。

在向现有应用添加 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 后，create 命令会向 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/docs/mastra-platform/configuration)。

## 查询 Observability 数据

项目开始向 Mastra Platform Observability 发布 Trace、日志或评分后，可以在终端中使用 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 Reference](https://mastra.zisheng.pro/reference/cli/mastra)。

## 相关内容

- 📹 [Mastra Observability 与 Studio workshop](https://www.youtube.com/watch?v=dKO_a3RPra0)