Mastra 平台 exporter

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

备注

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

自托管或独立应用

如果在自己的基础设施上托管 Mastra 应用（而不是 Mastra 平台），仍需要已部署的 Studio 项目才能查看 Trace、日志和指标。MastraPlatformExporter 会将数据发送到 Studio 项目，因此使用前必须先有一个项目。

1. 如果还没有项目，请创建 Mastra 项目。
2. 使用 mastra studio deploy 将 Studio 部署到 Mastra 平台。
3. 按照下面的快速开始步骤创建 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

运行以下命令：

mastra auth tokens create exporter-token

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

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

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

将 token 设置为环境变量：

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>

2. 查找 projectId

运行以下命令：

mastra studio deploy list

输出类似：

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

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

<your-project-id>

将其设置为环境变量：

.env

MASTRA_PROJECT_ID=<your-project-id>

3. 设置环境变量

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

.env

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

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

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai

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

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

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

4. 启用 MastraPlatformExporter

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

src/mastra/index.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。

完整可观测性配置结构请参阅可观测性配置参考。

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

src/mastra/index.ts

new MastraPlatformExporter()

设置 MASTRA_PLATFORM_ACCESS_TOKEN 和 MASTRA_PROJECT_ID 后，MastraPlatformExporter 会将数据发送到配置的 Mastra 平台项目。如果还设置了 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT，则会将数据发送到该 collector。所有配置选项请参阅 MastraPlatformExporter 参考。

推荐配置

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

src/mastra/index.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。

.env

MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com

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

src/mastra/index.ts

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

在 Mastra Studio 中查看数据

启用 MastraPlatformExporter 后，在 Mastra Studio 中打开项目，检查导出的数据。

• 打开 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 概览
• MastraStorageExporter