Mastra 推出 Span Queries：按 span 过滤分组定位编码智能体常见故障

推出 Span 查询

找出你的编码智能体最常见的故障并加以修复。

2026年10月28日

阅读时长 5 分钟

你现在可以使用 span 查询来过滤并分组所有 trace 中的单个 span。Mastra platform 和 Studio 支持按时间范围、类型、名称、状态、错误、耗时等条件过滤和分组 span。你的编码智能体可以运行相同的查询，然后修复它发现的问题。

Trace 查询可以按 trace 深处的细节进行过滤，例如失败的工具调用，但会返回整个 trace，使有问题的调用更难被发现。Span 查询粒度更细，会在每个 trace 内搜索，只返回匹配的 span。 Span 查询可用于对匹配的 span 进行分组或聚合，从而生成计数、错误率和延迟等指标。使用它们可以找出哪个工具正在失败或变慢，或跟踪工具随时间的延迟，然后使用带有相同过滤条件的 span 查询来检查有问题的调用。每条查询最多可组合 100 个条件，使用的字段包括

、 spanType, entityName, status, durationMs和 parentEntityName。Span 查询每页最多返回 1,000 个 span，span 分组最多可按 2 个维度分组，时间范围为最长 365 天的 timeRange 。

Span 查询适用于 Mastra platform，以及 storage.observability 使用 DuckDB、PostgreSQL 或 ClickHouse 的自托管 Mastra 项目。如果你的 trace 数据位于 Mastra 之外，你可以通过 trace 导入.

开始使用

Span 查询需要平台访问令牌和你的项目 ID，并随每个请求一起发送。请使用适用于你项目所在区域的正确 Mastra 可观测性基础 URL ：

美国: https://observability.mastra.ai
欧盟: https://observability.eu.mastra.ai

运行 span 查询有四种方式：Mastra CLI、Mastra platform 和 Studio、Mastra Client SDK，以及可观测性端点。下面的每个代码示例都会按工具对最近 7 天的工具调用进行分组，然后找出以错误结束的工具调用。

Mastra CLI

全局安装或升级 Mastra CLI：

终端

npm install -g mastra@latest

note需要 mastra@1.36.0 或更高版本，添加于 PR #28036.

运行 mastra api span aggregate 命令，查看每个工具的调用次数、错误率和 p95 延迟。CLI 会从你的环境中读取 MASTRA_PLATFORM_ACCESS_TOKEN 和 MASTRA_PROJECT_ID ：

终端

mastra api --url https://observability.mastra.ai span aggregate '{
  "timeRange": { "from": "2026-10-21T00:00:00.000Z", "to": "2026-10-28T00:00:00.000Z" },
  "where": { "op": "eq", "left": { "path": "spanType" }, "right": { "literal": "tool_call" } },
  "groupBy": ["entityName"],
  "measures": ["count", "errorRate", "duration.p95"],
  "orderBy": { "field": "errorRate", "direction": "desc" }
}'

运行 mastra api span query 命令，查找以错误结束的工具调用：

终端

mastra api --url https://observability.mastra.ai span query '{
  "timeRange": { "from": "2026-10-21T00:00:00.000Z", "to": "2026-10-28T00:00:00.000Z" },
  "where": {
    "op": "and",
    "args": [
      { "op": "eq", "left": { "path": "spanType" }, "right": { "literal": "tool_call" } },
      { "op": "eq", "left": { "path": "status" }, "right": { "literal": "error" } }
    ]
  }
}'

Mastra 平台和 Studio

在 Mastra 平台和 Studio 上， Spans 标签页可让你按时间范围、span 类型、span 名称、状态、错误、持续时间等条件进行筛选。

Mastra 客户端 SDK

终端

npm install @mastra/client-js@latest

note

需要 @mastra/client-js@1.57.0 或更高版本，添加于 PR #25920 和 PR #27827.

src/client.ts

import { MastraClient } from "@mastra/client-js";
 
export const mastraClient = new MastraClient({
  baseUrl: "https://observability.mastra.ai",
  headers: {
    Authorization: `Bearer ${process.env.MASTRA_PLATFORM_ACCESS_TOKEN}`,
    "X-Mastra-Project-Id": process.env.MASTRA_PROJECT_ID!
  }
});

使用 aggregateSpans() 查看每个工具的调用次数、错误率和 p95 延迟，问题最严重的排在最前面：

src/aggregate-spans.ts

import { mastraClient } from "./client";
 
const { rows } = await mastraClient.aggregateSpans({
  timeRange: {
    from: "2026-10-21T00:00:00.000Z",
    to: "2026-10-28T00:00:00.000Z"
  },
  where: {
    op: "eq",
    left: { path: "spanType" },
    right: { literal: "tool_call" }
  },
  groupBy: ["entityName"],
  measures: ["count", "errorRate", "duration.p95"],
  orderBy: { field: "errorRate", direction: "desc" }
});

添加一个 interval 以跟踪工具随时间的延迟：

src/tool-latency.ts

import { mastraClient } from "./client";
 
const { rows } = await mastraClient.aggregateSpans({
  timeRange: {
    from: "2026-10-21T00:00:00.000Z",
    to: "2026-10-28T00:00:00.000Z"
  },
  where: {
    op: "eq",
    left: { path: "spanType" },
    right: { literal: "tool_call" }
  },
  groupBy: ["entityName"],
  interval: "1d",
  measures: ["duration.p50", "duration.p95", "duration.p99"]
});

使用 querySpans() 查找以错误结束的工具调用：

src/spans.ts

import { mastraClient } from "./client";
 
const { spans } = await mastraClient.querySpans({
  timeRange: {
    from: "2026-10-21T00:00:00.000Z",
    to: "2026-10-28T00:00:00.000Z"
  },
  where: {
    op: "and",
    args: [
      { op: "eq", left: { path: "spanType" }, right: { literal: "tool_call" } },
      { op: "eq", left: { path: "status" }, right: { literal: "error" } }
    ]
  }
});