Mastra platform 上的 Observability

Mastra Platform Observability 会从 Mastra 应用收集 traces、logs、metrics、scores 和 feedback。当你需要托管可观测性，而又不想部署 Studio 或 Server 或配置本地可观测性存储时，请使用它。

快速开始

选择与你的项目匹配的设置路径。

新项目

创建一个托管的 Mastra 项目，并在提示时启用 Mastra Platform Observability：

npm

npm create mastra@latest

pnpm

pnpm create mastra

Yarn

yarn create mastra

Bun

bunx create-mastra

create 命令会通过 Mastra Platform 进行身份验证并创建可观测性项目。然后它会创建 access token，并将 MASTRA_PLATFORM_ACCESS_TOKEN 和 MASTRA_PROJECT_ID 写入 .env。

现有项目

如果你要将 Mastra 添加到现有应用，请运行 mastra init 并在提示时启用 Mastra Observability：

npm

npx mastra init

pnpm

pnpm dlx mastra init

Yarn

yarn dlx mastra init

Bun

bun x mastra init

init 命令允许你选择现有平台项目或创建一个。然后它会创建 access token 并将凭据写入 .env。

手动配置

如果你跳过了平台设置或自动创建失败，请使用手动配置。

1. 在 Mastra Platform 中创建或打开项目。
2. 为项目的组织创建 access token。
3. 从项目页面复制项目 ID。
4. 将两个值都添加到 .env：

.env

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

在可观测性配置中注册 MastraPlatformExporter：

src/mastra/index.ts

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

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

exporter 从环境中读取 access token 和项目 ID。请保持 serviceName 稳定，以便在筛选可观测性数据时区分应用和部署。

MastraPlatformExporter 会发送已结束的 spans、logs、metrics、scores 和 feedback。它会缓冲事件，并在达到 1,000 个事件或等待五秒后发送批次。Model chunk spans 不会被导出。

备注

MastraPlatformExporter 取代了 CloudExporter。CloudExporter 仍可用于向后兼容，但已弃用。新代码请使用 MastraPlatformExporter。

在本地存储数据

如果你还想将可观测性数据持久化到已配置的 Mastra 存储并在本地 Studio 中检查，请添加 MastraStorageExporter：

src/mastra/index.ts

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

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

存储要求和配置请参阅 Mastra storage exporter。

查看可观测性数据

在 Mastra Platform 中打开项目，检查导出的 traces、logs、metrics 和 scores。无需部署 Studio 或 Server。通过下文所述的托管 feedback API 查询导出的 feedback。

使用一致的 serviceName 来筛选特定应用或部署的数据。

查询可观测性数据

使用 Mastra CLI 从终端浏览托管的 traces：

npm

npx mastra api trace list

pnpm

pnpm dlx mastra api trace list

Yarn

yarn dlx mastra api trace list

Bun

bun x mastra api trace list

CLI 会从项目环境读取 MASTRA_PLATFORM_ACCESS_TOKEN 和 MASTRA_PROJECT_ID，并默认指向美国可观测性端点。其他身份验证选项和区域端点请参阅 CLI 目标解析。

使用 mastra api trace query 按字段或相关 spans 查找已完成的 traces。例如，查找根 span 耗时超过五秒的 traces：

npx mastra api trace query '{
  "timeRange": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-08-08T00:00:00.000Z"
  },
  "where": {
    "op": "gt",
    "left": { "path": "durationMs" },
    "right": { "literal": 5000 }
  },
  "page": { "limit": 25 }
}'

选择一个包含已导出 traces 的时间范围，最多 31 天。结果显示在 data.traces 中。

Mastra Platform 使用与 Mastra Server 相同的 trace 查询端点和请求格式。HTTP 请求、支持的过滤器、分页、轮询和字段发现请参阅高级 trace 查询参考。

你可以通过 HTTP 查询导出的 feedback。当前状态、区域端点、身份验证、项目作用域以及支持的查询参数（例如 traceId 和 environment）请参阅 Feedback API。

你可以通过 HTTP、MastraClient 或 mastra api metric 查询导出的 metrics。区域端点、身份验证、项目作用域和支持的端点请参阅 Metrics API。

导入现有 traces

使用 mastra traces import 将现有 trace 历史从支持的可观测性提供器迁移到现有 Mastra Platform 项目。该命令会在源端读取并验证完整 traces，将其转换为 Mastra spans，然后使用共享工作流进行准备、上传、恢复和验证。

导入命令目前支持 Langfuse。其他提供器在添加适配器后可以使用相同的工作流。

提供器	命令参数	源要求
Langfuse	langfuse	Langfuse Cloud 或自托管的 Langfuse v4 或更高版本

前提条件

开始导入之前，你需要：

• 一个 Mastra Platform 项目。
• 通过 mastra auth login 进行 Mastra Platform 身份验证，或在无头环境中提供 MASTRA_API_TOKEN 和 MASTRA_ORG_ID。
• 使用交互式登录时，上传和回读需要 MASTRA_PLATFORM_ACCESS_TOKEN。dry run 不需要此 token。
• 支持的源提供器的凭据。
• 足够的本地磁盘空间以临时存储准备好的 traces。

配置目标

对于交互式导入，请登录并选择拥有目标项目的组织：

npx mastra auth login
npx mastra auth orgs switch

交互式登录会授权项目发现。在上传或验证 traces 之前，设置目标项目使用的 Platform access token：

.env

MASTRA_PLATFORM_ACCESS_TOKEN=<mastra-platform-access-token>

如果 mastra init 为项目配置了可观测性，请使用它写入 .env 的 token。否则，请在 Mastra Platform 中创建 access token。

你可以在没有此 token 的情况下运行 --dry-run，因为 dry run 不会联系 collector 或查询 API。

--target-project 指定目标：接收 traces 的 Mastra Platform 项目。使用项目名称、slug 或 ID 指定它，或设置 MASTRA_PROJECT_ID：

npx mastra traces import langfuse --target-project my-mastra-project --dry-run

--target-project flag 优先于 MASTRA_PROJECT_ID。如果两者都未提供，CLI 会使用 .mastra-project.json 中关联的项目。

源项目不是命令行选项。.env 中的提供器凭据会选择它，准备摘要会在上传任何内容之前标明它。

对于无头环境，请设置 API token 和组织 ID。命令使用 MASTRA_API_TOKEN 进行项目发现、上传和回读。设置项目 ID 或传入 --target-project：

.env

MASTRA_API_TOKEN=<mastra-api-token>
MASTRA_ORG_ID=<organization-id>
MASTRA_PROJECT_ID=<project-id>

配置 Langfuse

Langfuse API 密钥属于一个 Langfuse 项目，因此它们也会选择源项目。在 Langfuse 中创建项目 API 密钥，然后将它们添加到运行命令所在目录的 .env 或 .env.local：

.env

LANGFUSE_PUBLIC_KEY=<langfuse-public-key>
LANGFUSE_SECRET_KEY=<langfuse-secret-key>

Langfuse Cloud 默认使用位于 https://cloud.langfuse.com 的欧盟区域。将 LANGFUSE_BASE_URL 设置为美国、日本或 HIPAA Cloud 的区域主机，或设置为自托管实例的 origin：

.env

LANGFUSE_BASE_URL=https://us.cloud.langfuse.com

预览导入

在上传前运行 dry run：

npx mastra traces import langfuse --target-project my-mastra-project --dry-run

dry run 会读取源、在本地准备有效的 Mastra traces，并报告：

• 源 Langfuse 项目的名称和 ID，以及目标 Mastra Platform 项目。
• 固定的导入窗口。
• 已准备和已跳过的 trace 与 span 数量。
• 准备好的本地数据大小。
• report.json 中的提供器警告和跳过原因。

它不会上传 traces。命令会打印一条 --resume 命令，之后可在不再次读取源的情况下上传准备好的数据。

选择导入窗口

默认情况下，命令选择最近 30 天，截止到导入开始。使用 --since 和 --until 选择更小的窗口：

npx mastra traces import langfuse \
  --target-project my-mastra-project \
  --since "$SINCE" \
  --until "$UNTIL" \
  --dry-run

将 SINCE 和 UNTIL 设置为 ISO 8601 日期或时间戳。适用以下规则：

• --until 不能位于未来，也不能超出当前 30 天的 Platform 保留期。
• --since 必须早于 --until，并且位于当前保留期内。
• 所选窗口不能超过 30 天。
• 如果只设置 --until，默认起点为 --until 之前 30 天与当前保留边界中较晚的一个。

使用早期 --from 和 --to 名称编写的命令仍然可用。

trace 的资格基于根 observation 的开始时间。Langfuse 适配器会在所选窗口中发现根，然后读取每个所选 trace 当前可用的所有 observations。如果可用的父子树或时间戳无效，它会跳过整个 trace。

上传并验证

在不带 --dry-run 的情况下运行命令以上传准备好的 traces：

npx mastra traces import langfuse --target-project my-mastra-project

CLI 会显示准备摘要并在上传前请求确认。在自动化环境中传入 --yes 可跳过此提示：

npx mastra traces import langfuse --target-project my-mastra-project --yes

导入器会将每个 trace 保留在单个上传请求中，并且仅在 Mastra Platform 确认批次后记录检查点进度。临时的源和目标故障会使用有界重试。

在准备好的每个 trace 都得到确认后，导入器会回读最多 10 个 traces 的确定性样本。它会验证 span ID、父链接、名称、span 类型、事件 flags、时间戳以及是否存在错误。它不会回读或比较 input、output、attributes、metadata 或 tags。

如果回读尚不可用或样本 trace 存在差异，导入会暂停并保留准备好的数据。恢复导入可重试验证，而不会再次上传已确认的 traces。

恢复导入

当 dry run、取消、中断、上传失败或验证暂停导致导入未完成时，请使用 CLI 打印的确切命令：

npx mastra traces import langfuse \
  --resume 00000000-0000-0000-0000-000000000000 \
  --target-project my-mastra-project

恢复的导入必须使用原始提供器和目标项目。其保存的日期窗口无法更改，因此 --since、--until 和 --dry-run 不能与 --resume 组合使用。

恢复行为取决于命令停止的位置：

• 中断的准备会再次读取并准备源。
• 中断的上传会从第一个未确认的 trace 开始。
• 暂停的验证会重试回读，而不会重新上传已确认的 traces。
• 已完成的导入会报告它已完成，并重试任何剩余的本地清理。

本地文件和清理

导入状态存储在：

~/.mastra/imports/traces/<target-project-id>/<import-id>/

文件	用途	生命周期
manifest.json	存储源标识、日期窗口、计数和已确认进度。	完成后保留。
traces.jsonl	每行存储一个完整的规范化 trace。	dry run 和未完成的导入会保留，成功验证后移除。
report.json	存储计数、警告、跳过样本和验证结果。	写入后保留。

这些文件可能包含 trace 内容。Mastra 会以仅限本地用户访问的权限创建导入目录和文件。请保护运行导入的机器和账户。

导入的数据和限制

对于 Langfuse 导入：

• Observations 会转换为带有父子关系和时间戳的 Mastra spans。
• Langfuse 的 AGENT、TOOL 和 EVALUATOR observations，以及携带 OpenTelemetry GenAI 属性（例如 gen_ai.operation.name: invoke_agent）的普通 spans，会保留其 primitive 类型和名称。Mastra Platform 会在 Primitive type 和 Primitive name 列中显示它们，并像原生 traces 一样将它们纳入这些过滤器。
• 名称、input、output、错误、模型详情、用量、成本、tags 和源上下文等支持的字段会在存在时进行映射。
• 你在 Langfuse 中设置的环境（例如 staging）会保留。Langfuse 内置的 default 环境不会被复制。这些 traces 在 Mastra 中没有环境，Mastra Studio 会为每个环境显示它们。
• 目标 trace 和 span ID 是确定性的。原始 Langfuse ID 保留在 span metadata 中以供关联。
• 未知的 Langfuse observation 类型会转换为通用 spans 并产生警告，而不是被静默丢弃。
• 仅导入 trace observations。Scores、feedback、datasets、attachments 和 logs 不会被导入。

共享导入器还会应用以下限制：

• 准备好的本地 trace 数据每次导入限制为 5 GiB。如果导入达到此限制，请使用更小的日期窗口。
• 完整 trace 必须符合导入器 4 MiB 的上传负载限制。更大的 trace 会被跳过，并以 trace_too_large 原因记录。
• trace 永远不会拆分到多个上传请求中。

在 dry run 或完成导入后查看 report.json，准确了解已准备、跳过、确认和验证的内容。

完整的选项和环境变量参考请参阅 mastra traces import CLI 参考。

下一步

• 📹 Mastra 可观测性和 Studio 研讨会
• 配置 Mastra Platform
• 了解可观测性
• 配置 MastraPlatformExporter