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

# Mastra 平台 exporter

`MastraPlatformExporter` 会将 Trace、日志、指标、分数和反馈发送到 Mastra 平台。可用它将任何 Mastra 应用的可观测性数据路由到 Mastra 平台中的托管项目。

> **备注:** `MastraPlatformExporter` 以前名为 `CloudExporter`。为向后兼容，原来的 `CloudExporter` 类仍从 `@mastra/observability` 导出，但已弃用。新代码应使用 `MastraPlatformExporter`。

> **自托管或独立应用:** 如果在自己的基础设施上托管 Mastra 应用（而不是 Mastra 平台），仍需要已部署的 Studio 项目才能查看 Trace、日志和指标。`MastraPlatformExporter` 会将数据发送到 Studio 项目，因此使用前必须先有一个项目。
>
> 1. 如果还没有项目，请[创建 Mastra 项目](https://mastra.zisheng.pro/guides/getting-started/quickstart)。
> 2. 使用 `mastra studio deploy` 将 [Studio 部署](https://mastra.zisheng.pro/docs/studio/deployment)到 Mastra 平台。
> 3. 按照下面的[快速开始步骤](#quickstart)创建 access token 并查找项目 ID。

## 版本兼容性

- `MastraPlatformExporter` 从 `@mastra/observability@1.12.0` 开始提供。在 `1.8.0` 到 `1.11.x` 中，同一 exporter 仅以 `CloudExporter` 名称提供。构造函数签名和环境变量相同。
- 在 `@mastra/observability@1.8.0` 到 `1.9.1` 中，除 `MASTRA_PLATFORM_ACCESS_TOKEN` 和 `MASTRA_PROJECT_ID` 外，还需设置 `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai`。
- 从 `@mastra/observability@1.9.2` 开始，exporter 默认为 `https://observability.mastra.ai`，因此只有要将 telemetry 发送到其他 collector 时才需要 `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`。

## 快速开始

要连接 `MastraPlatformExporter`，请创建 access token、查找目标 `projectId`，并将 exporter 添加到可观测性配置。

### 1. 创建 access token

运行以下命令：

```bash
mastra auth tokens create exporter-token
```

该命令会输出 token secret，可将其用作 `MASTRA_PLATFORM_ACCESS_TOKEN`。

如果已有 access token，也可以从 Mastra 平台复制 **Observability** 值。可在以下任一位置找到：

- 在 **Projects** 页面打开项目列表，在项目卡片上找到 **Observability** 行。
- 在项目 **Overview** 页面中，找到部署 URL 正下方的 **Observability** 行。

将 token 设置为环境变量：

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
```

### 2. 查找 `projectId`

运行以下命令：

```bash
mastra studio deploy list
```

输出类似：

```text
✅ <your-project-name> (<your-project-id>)
   Latest:   00000000-0000-0000-0000-000000000000 — running
   URL:      https://260407.studio.mastra.cloud
```

在此输出中，括号中的值就是 `projectId`：

```text
<your-project-id>
```

将其设置为环境变量：

```bash
MASTRA_PROJECT_ID=<your-project-id>
```

### 3. 设置环境变量

在环境中设置这两个值，使 `MastraPlatformExporter` 能够完成身份验证，并将 telemetry 路由到正确的项目：

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
MASTRA_PROJECT_ID=<your-project-id>
```

如果使用 `@mastra/observability@1.8.0` 到 `1.9.1`，还需要显式设置 Mastra 平台 collector：

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai
```

如果要将 telemetry 发送到 Mastra 平台以外的位置，也请设置 `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`。可以传入 base origin，或以 `/spans/publish` 结尾的完整 Trace publish URL。

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
```

传入 base origin 时，`MastraPlatformExporter` 会自动派生 Trace、日志、指标、分数和反馈对应的 publish URL。

### 4. 启用 `MastraPlatformExporter`

以下示例演示如何将 `MastraPlatformExporter` 添加到可观测性配置：

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

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

请在可观测性配置中设置 `serviceName`，而不是在 `MastraPlatformExporter` 上设置。

使用稳定的 `serviceName` 值。在 Studio 中，可以通过 **Deployments → Service Name** 过滤 Trace，因此一致的名称更便于查找 Trace。

完整可观测性配置结构请参阅[可观测性配置参考](https://mastra.zisheng.pro/reference/observability/tracing/configuration)。

也可以完全依赖环境变量：

```ts
new MastraPlatformExporter()
```

设置 `MASTRA_PLATFORM_ACCESS_TOKEN` 和 `MASTRA_PROJECT_ID` 后，`MastraPlatformExporter` 会将数据发送到配置的 Mastra 平台项目。如果还设置了 `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`，则会将数据发送到该 collector。所有配置选项请参阅 [MastraPlatformExporter 参考](https://mastra.zisheng.pro/reference/observability/tracing/exporters/mastra-platform-exporter)。

## 推荐配置

如果还希望在 Studio 中检查本地 Trace，或将可观测性数据持久化到配置的存储，请包含 `MastraStorageExporter`。

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

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

## 完整配置

`MastraPlatformExporter` 默认使用 Mastra 平台。如果要将 telemetry 发送到其他 collector，请在环境中设置 `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`，或在代码中传入 `endpoint`。

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
```

以下示例演示如何在代码中覆盖 collector endpoint 和批处理行为：

```ts
new MastraPlatformExporter({
  endpoint: 'https://collector.example.com',
  maxBatchSize: 1000,
  maxBatchWaitMs: 5000,
  logLevel: 'info',
})
```

## 在 Mastra Studio 中查看数据

启用 `MastraPlatformExporter` 后，在 [Mastra Studio](https://projects.mastra.ai) 中打开项目，检查导出的数据。

- 打开 `MASTRA_PROJECT_ID` 指向的项目，选择 **Open Studio**。
- 在 Studio 中前往 **Traces**，检查 Agent 和 Workflow Trace。
- 打开过滤菜单，使用 **Deployments → Service Name** 隔离特定应用或部署的 Trace。
- 使用项目仪表板中的 **Logs** 页面检查导出的日志。

使用 Mastra Studio 部署时，请将 **Deployment → Service Name** 设为稳定值，并与可观测性配置中的 `serviceName` 保持一致。当多个服务或部署向同一项目发送数据时，这样可以更轻松地在 Studio 中通过 **Deployments → Service Name** 过滤 Trace。

## 性能

> **信息:** MastraPlatformExporter 使用批处理优化网络使用。事件会缓冲并分批发送，从而减少开销，同时保持近乎实时的可见性。

### 批处理行为

- 事件最多批处理到 `maxBatchSize`（默认 1000）。
- 批次装满或经过 `maxBatchWaitMs`（默认 5 秒）后发送。
- 失败的批次会使用指数退避重试。
- 如果 Mastra Studio 无法访问，exporter 会优雅降级。

## 相关内容

- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [MastraStorageExporter](https://mastra.zisheng.pro/docs/observability/integrations/exporters/mastra-storage)