Mastra adds span queries: traces no longer come back whole, so failing tool calls surface directly
Synopsis
Mastra has introduced span queries, moving observability queries from the whole trace down to individual spans inside it. Trace queries could already filter on deep details such as a failed tool call, but they still returned the entire trace, making the problematic call hard to spot. Span queries search within each trace and return only matching spans, and matching spans can be grouped or aggregated into counts, error rates and latency to show which tool is failing or slow.
Interpretation
Mastra's trace queries can now reach the span level inside a single trace, filtering and grouping by time range, type, name, status, error, duration and more. Trace queries could filter on deep details such as a failed tool call, but returned the whole trace, so the problematic call was hard to pick out. Span queries search within each trace and return just the matching spans, so the result is the set of calls that need inspection.
Matching spans can be grouped or aggregated into measures such as call counts, error rates and p95 latency, which indicate which tool is failing or slow. Those aggregates pair with the same filters to return to the specific problematic calls for inspection. Each query combines up to 100 conditions over fields including spanType, entityName, status, durationMs and parentEntityName; it returns up to 1,000 spans per page, and span groups group by up to 2 dimensions over a time range of up to 365 days.
Queries run through four entry points: the Mastra CLI, Mastra platform and Studio, the Mastra Client SDK, and observability endpoints. The Spans tab on Mastra platform and Studio offers filtering by time range, span type, span name, status, error, duration and more. Queries require a platform access token and project ID sent with each request, and use the observability base URL for the project's region; self-hosted projects need storage.observability on DuckDB, PostgreSQL or ClickHouse, and trace data outside Mastra can be brought in with trace imports.
Perspective
The demonstrated scope is Mastra platform and Studio, plus self-hosted Mastra projects whose storage.observability uses DuckDB, PostgreSQL or ClickHouse; users whose trace data lives outside Mastra can bring existing history over with trace imports. Queries need a platform access token and project ID, and use the US or EU observability base URL for the project's region.
A query returns up to 1,000 spans per page, span groups group by up to 2 dimensions over a time range of up to 365 days, and each query combines up to 100 conditions; these limits bound what a single query covers. Self-hosted use requires storage.observability on DuckDB, PostgreSQL or ClickHouse, and other storage configurations fall outside the stated support.