Mastra 可观测性 Traces 测试指南从本地冒烟测试到云端 Trace 管线验证【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇指南以 Mastra 仓库中 smoke test 套件的 Traces 测试为骨架见 traces.md完整讲解如何验证 Mastra 的可观测性 traces 是否被正确采集与展示。你将掌握Studio 与 Server 两类 trace 来源的区分方法、/api/observability/traces本地与云端 API 的调用与判定标准、WorkOS Token 自动刷新脚本以及从telemetry配置到MastraStorageExporter底层实现的排障链路。该指南适用于--test traces冒烟测试场景也可作为 Mastra 应用可观测性调试的独立参考。Traces 测试的定位与目的在 Mastra 的冒烟测试体系中见 SKILL.md 的 Mandatory Test ChecklistTraces 是第 5 项必测内容可通过--test traces单独执行也可作为完整测试的一部分运行。其核心目的是验证可观测性 traces 是否被正确采集并在 Studio 中展示。执行--test traces前需要满足两个前置条件必须先运行 agent / tool / workflow 测试为 traces 页面制造数据云端--env staging/--env production场景下Studio 与 Server 都需要完成部署。从测试设计上Traces 测试覆盖三条链路Studio 中的 UI 交互痕迹agent chat、tool 调用、通过 curl 直连 Server API 生成的 trace、以及本地开发服务器的 in-memory trace 存储。一、本地环境的 Traces 验证流程1. 在 Studio 中检查 Observability 页面打开/observability路由完成以下核对项页面是否正常加载是否出现错误提示记录页面上已有的 traces查找此前 agent chat、tool 运行留下的 traces记录每条 trace 展示的信息名称name、时间戳timestamp、耗时duration、状态status点击单条 trace 展开详情记录展示的输入/输出、时间信息和错误状态。从源码结构看observability.ts 定义了完整的 trace 相关路由GET /observability/traces分页列表、GET /observability/traces/:traceId单条 trace 全量 spans、GET /observability/traces/:traceId/spans/:spanId单 span 详情等Studio 前端正是在这些 API 之上渲染 trace 列表与详情面板。2. 通过本地 API 校验--skip-browser场景本地开发服务器默认localhost:4111暴露了与云端完全相同的端点且无需鉴权# 列出最近的 spans响应结构{ pagination, spans } curl -s http://localhost:4111/api/observability/traces?page0perPage20 | jq . # 按 traceId 获取单条 tracetraceId 来自此前 agent/workflow 的响应 curl -s http://localhost:4111/api/observability/traces/traceId | jq .响应结构要点GET /api/observability/traces返回的是{ pagination: { total, page, perPage, hasMore }, spans: [...] }不是裸数组也没有traces键。spans数组中的每个条目包含spanType取值为agent_run、tool_call、workflow_run、scorer_run、traceId、时间戳和 payload。快速通过判定quick pass checkcurl -s http://localhost:4111/api/observability/traces?page0perPage100 | \ jq {total: .pagination.total, byType: ([.spans[].spanType] | group_by(.) | map({t: .[0], n: length}))}本地通过标准Pass criteria运行 agent / tool / workflow 测试后.pagination.total 0.spans中包含预期的spanTypeagent_run、workflow_run、scorer_run若 agent 调用了工具还应有tool_call先前 generate/workflow 响应中返回的traceId可以通过/observability/traces/:traceId成功解析。⚠️ 关键注意事项本地 traces 只存在于内存中通过MastraStorageExporterdev server 重启即丢失。因此必须在同一次 dev server 会话内运行 agent/tool/workflow 测试和 traces 测试。二、云端环境的 Traces 验证流程1. 通过 Server API 生成 traceCloud Only对于--env staging或--env production环境直接调用 Server 的 agent generate 端点制造一条新 tracecurl -X POST server-url/api/agents/weather-agent/generate \ -H Content-Type: application/json \ -d {messages:[{role:user,content:Weather in Paris?}]}执行后记录响应内容然后刷新/observability页面检查是否出现来自 Server API 调用的新 trace记录该 trace 出现所需的时间如果出现的话。2. 区分 Studio 与 Server 两类 Trace 来源SourceHow GeneratedIdentifierStudioUI 交互chat、tool 运行来自 Studio 域名Server直接 API 调用来自 Server 域名这个区分在排障时很重要只有 Studio traces 而没有 Server traces往往指向 Server 侧的 token 或部署问题而非采集管线本身的问题。3. 直连 Trace API 验证管线Cloud Only当 UI 上 traces 不出现、但需要验证 trace 管线本身是否工作正常时可以直接查询云端 collector。Mobs-Query URLsEnvironmentURLProductionhttps://mobs-query-vgvrl5lbxq-uc.a.run.appStaginghttps://mobs-query-pvyw2kfhjq-uc.a.run.app获取认证 Token执行mastra auth login后凭据保存在~/.mastra/credentials.json{ token: eyJhbG..., // Access token (5 min expiry) refreshToken: eyJhbG..., // Refresh token (long-lived) user: { id: ..., email: ... }, organizationId: org_01KN..., currentOrgId: org_01KN... }Token 自动刷新脚本WorkOS token 的有效期只有5 分钟冒烟测试耗时可能超过该窗口因此文档提供了自动刷新 helperget_valid_token() { local PLATFORM_URL${1:-https://platform.mastra.ai} local TOKEN$(jq -r .token ~/.mastra/credentials.json) local ORG_ID$(jq -r .currentOrgId // .organizationId ~/.mastra/credentials.json) # 先尝试当前 token local VERIFY$(curl -s $PLATFORM_URL/v1/auth/verify \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID) if echo $VERIFY | jq -e .user /dev/null 21; then echo $TOKEN return 0 fi # Token 已过期——尝试 refresh local REFRESH_TOKEN$(jq -r .refreshToken ~/.mastra/credentials.json) if [ -z $REFRESH_TOKEN ] || [ $REFRESH_TOKEN null ]; then echo No refresh token. Re-login required. 2 return 1 fi local REFRESH_RESULT$(curl -s $PLATFORM_URL/v1/auth/refresh-token \ -X POST \ -H Content-Type: application/json \ -d {\refreshToken\: \$REFRESH_TOKEN\}) if echo $REFRESH_RESULT | jq -e .accessToken /dev/null 21; then local NEW_TOKEN$(echo $REFRESH_RESULT | jq -r .accessToken) local NEW_REFRESH$(echo $REFRESH_RESULT | jq -r .refreshToken) # 回写凭据文件 jq --arg t $NEW_TOKEN --arg r $NEW_REFRESH \ .token $t | .refreshToken $r \ ~/.mastra/credentials.json ~/.mastra/credentials.json.tmp \ mv ~/.mastra/credentials.json.tmp ~/.mastra/credentials.json echo $NEW_TOKEN return 0 fi echo Refresh failed. Re-login required. 2 return 1 } # 用法 TOKEN$(get_valid_token https://platform.mastra.ai) || exit 1脚本逻辑清晰先/v1/auth/verify验证当前 token有效则直接使用过期则用 refreshToken 调用/v1/auth/refresh-token换取新 token 并回写文件两种方式都失败时提示重新登录。查询 Traces# 从配置文件读取项目信息 PROJECT_ID$(jq -r .projectId .mastra-project.json) # 或 .mastra-project-staging.json ORG_ID$(jq -r .organizationId .mastra-project.json) TOKEN$(get_valid_token https://platform.mastra.ai) # Production curl -s https://mobs-query-vgvrl5lbxq-uc.a.run.app/api/observability/traces?page0perPage10resourceId$PROJECT_ID \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID | jq . # Staging TOKEN$(get_valid_token https://platform.staging.mastra.ai) curl -s https://mobs-query-pvyw2kfhjq-uc.a.run.app/api/observability/traces?page0perPage10resourceId$PROJECT_ID \ -H Authorization: Bearer $TOKEN \ -H x-organization-id: $ORG_ID | jq .注意这里的resourceId指向项目 ID用于按项目隔离查询。冒烟测试框架支持多环境配置staging 使用.mastra-project-staging.jsonproduction 使用.mastra-project.json见 SKILL.md 的 Multi-Environment Support 一节。4. 云端 Trace 响应结构与过滤云端 collector 的响应结构与本地 API 不同顶层是traces数组{ pagination: { total: 10, page: 0, perPage: 10, hasMore: false }, traces: [ { traceId: 37f0d68d760887e994135c984ebd7b89, name: agent run: weather-agent, spanType: agent_run, startedAt: 2026-04-08T15:29:27.123Z, endedAt: 2026-04-08T15:29:30.456Z, metadata: { buildId: ..., runId: ... }, requestContext: { user: { id: ..., email: ... } }, status: success } ] }关键字段说明FieldDescriptionmetadata.buildId部署 IDstudio 或 serverrequestContextStudio traces 存在已认证Server traces 为 nullspanTypeagent_run、tool_call、workflow_run等statussuccess、error、running过滤 Traces# 按时间范围URL 编码后的 JSON curl -s ...?startedAt%7B%22start%22%3A%222026-04-08T15%3A00%3A00.000Z%22%7D ... # 按资源 ID项目 curl -s ...?resourceId$PROJECT_ID ... # 按 run ID curl -s ...?runId$RUN_ID ...三、常见问题排障速查表SymptomLikely CauseFix完全没有 tracesOTel 未配置检查 mastra config 中的telemetry只有 Studio tracesServer token 问题重新部署 Server页面显示 Something went wrong认证/会话问题在 Studio 中重新认证出现CLOUD_EXPORTER警告缺少 token基础设施问题——记录在案四、本地与云端的行为差异本地--env localTraces 存储在内存中仅当 dev server 运行期间存在需要确认已安装mastra/observability。云端--env staging/productionTraces 发送到云端 collector跨会话持久化注意核对 Studio 与 Server 两端的 traces 是否都出现。五、从配置到存储Traces 管线的源码级解析Traces 测试文档反复强调“检查 mastra config 中的telemetry”而这在最新代码库中对应的是observability配置。以仓库中的 weather-agent 模板 为例一个完整的可观测性配置如下import { Observability, MastraStorageExporter, MastraPlatformExporter, SensitiveDataFilter, } from mastra/observability; export const mastra new Mastra({ // ...agents / workflows / scorers... storage: new LibSQLStore({ id: mastra-storage, // stores observability, scores, ... into persistent file storage url: file:./mastra.db, }), observability: new Observability({ configs: { default: { serviceName: mastra, exporters: [ new MastraStorageExporter(), // Persists observability events to Mastra Storage new MastraPlatformExporter(), // Sends observability events to Mastra Platform (if MASTRA_CLOUD_ACCESS_TOKEN is set) ], spanOutputProcessors: [ new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys ], }, }, }), });配置结构清晰对应冒烟测试的两个场景MastraStorageExporter支撑本地 in-memory / LibSQL 持久化MastraPlatformExporter支撑云端 collector 上报需要MASTRA_CLOUD_ACCESS_TOKENSensitiveDataFilter负责在导出前脱敏 API key、token、密码等敏感字段。1. MastraStorageExporter本地 traces 的存取原理MastraStorageExporter的实现在 mastra-storage.ts。它的工作方式是缓冲批量写入所有可观测性事件tracing、metric、log、score、feedback先进入内部EventBuffer满足以下任一条件即触发 flush达到maxBatchSize默认 1000 spans、达到maxBufferSize默认 10000 spans紧急冲刷、超过maxBatchWaitMs默认 5000ms时间窗、或存储策略为realtimeflush 失败时按retryDelayMs默认 500ms为基数做指数退避重试最大maxRetries次默认 4 次init时会从 Mastra 实例取 storage若取不到 observability store则发出MastraStorageExporter disabled: Storage not available警告——这正是冒烟测试中“完全没有 traces”时的第一条排查线索。这解释了本地环境的重要特性若使用内存存储未配置持久化 storetraces 自然只存活于 dev server 会话期间若使用LibSQLStore这类持久化 storefile:./mastra.db则 traces 会落盘。冒烟测试文档明确要求“在同一次 dev server 会话内运行测试”正是因为内存模式下重启即丢。2. spanTypetraces 的类型体系spanType是 trace 判定的核心维度其枚举定义在 tracing.ts。与冒烟测试通过标准直接相关的几个值agent_run一次 agent 运行tool_call一次工具调用另有mcp_tool_call、client_tool_call、provider_tool_call等细分类型workflow_run一次 workflow 运行scorer_run一次评分器scorer运行。每种 spanType 都有对应的属性与输入/输出类型定义。测试通过标准要求.spans同时出现agent_run、workflow_run、scorer_run正是为了证明三条核心执行路径agent、workflow、scorer都产生了可观测的 trace。3. 服务端 API 与旧参数兼容GET /observability/traces路由定义在 observability.ts从源码可以看到两类关键设计分页响应统一由listTracesResponseSchema约束为{ pagination, spans }结构与冒烟测试文档强调的响应形状一致路由通过transformLegacyParams兼容旧版参数dateRange→startedAt、nameagent run: x→entityIdx entityTypeagent、旧值entityTypeworkflow→ 规范化枚举值workflow_run。这意味着即使是旧代码库生成的数据也能用新 API 正常查询。4. 高级 Trace 查询进阶除了基础的列表/详情 API仓库还提供了功能更强大的POST /api/observability/traces/query端点见 trace-query.mdx。它支持递归谓词spans.some/spans.none/scores.some/scores.none、按threadId分组、游标分页与排序。例如查询存在失败的tool_callspan的 tracecurl --request POST \ --url http://localhost:4111/api/observability/traces/query \ --header Authorization: Bearer token \ --header Content-Type: application/json \ --data { timeRange: { from: 2026-08-01T00:00:00.000Z, to: 2026-08-08T00:00:00.000Z }, where: { spans: { some: { op: and, args: [ { op: eq, left: { path: spanType }, right: { literal: tool_call } }, { op: exists, path: error } ] } } } }该端点仅返回已完成的轻量 trace 投影且要求 observability store 支持高级 trace 查询501表示 store 不支持PostgreSQL 与 ClickHouse 默认有 15 秒查询超时可通过traceQueryTimeoutMs调整超时返回504。对于冒烟测试场景基础列表 API 通常已足够高级查询更适合在需要程序化筛选失败 trace 时使用。六、浏览器端检查步骤Browser Actions无论本地还是云端Traces 测试的最后一步都是浏览器动作验证Navigate to: /observability Wait: For traces to load Verify: At least one trace visible Click: On a trace row Verify: Details panel shows input/output # 云端环境追加 Execute: curl command to server Navigate to: /observability Click: Refresh or wait Verify: New server trace appears这与 SKILL.md 中 Local Studio Browser Smoke 的要求一致API 检查证明运行时端点可用浏览器检查证明 Studio UI 能加载、展示并渲染 trace 详情。若浏览器可访问性快照中文本不足应检查document.body.innerText或截图作为证据不要只依赖 API 输出。七、测试结果记录模板执行 Traces 测试时建议按以下表格记录观察结果CheckWhat to RecordTraces page加载行为、任何错误Studio traces此前操作产生了哪些 tracesTrace details展示的输入、输出、耗时Server tracesAPI 调用后是否出现 traces、出现耗时最终汇总进 smoke report例如## Smoke Test Results | Test | Status | Notes | | ------ | ------ | ----- | | Traces | ✅/❌ | 说明Studio/Server traces 是否都出现、traceId 是否可解析 |结语Traces 测试是 Mastra 可观测性闭环中最直接的验证手段本地场景下你通过/api/observability/traces在同一次 dev server 会话内验证 agent、workflow、scorer、tool 四类 span 是否产生、traceId是否可回溯云端场景下你通过 Server API 制造新 trace再借助 Mobs-Query 端点与自动刷新的 Token 脚本核对 collector 中的数据。遇到完全没有 traces时优先检查observability配置中的 exporters 是否包含MastraStorageExporter/MastraPlatformExporter、storage 是否可用遇到只有 Studio traces时优先检查 Server 侧的 token 与部署状态。结合本指南与仓库中的 traces.md、mastra-storage.ts、observability.ts 等源码即可在任意环境快速定位 trace 管线问题。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考