Mastra bekommt Trace-Abfragen, mit denen sich fehlgeschlagene Tool-Aufrufe und langsame Modellläufe aufspüren lassen

14. Oktober 2026Quelle: Mastra

Mastra hat Trace-Abfragen eingeführt, eine Funktion, die Traces nach bestimmten Kriterien filtert und findet, auch anhand von Details, die tief in einem Trace verschachtelt sind, etwa fehlgeschlagene Tool-Aufrufe, niedrige Scores und Daumen-runter-Feedback. Die Abfragen funktionieren in der Mastra-Plattform, im lokalen Studio, in der CLI, im Mastra Client SDK und über HTTP-Observability-Endpunkte.

Das Wichtigste in Kürze

Mastras Trace-Abfragen filtern Traces nach Zeit, Agent- oder Workflow-ID, Status, Score und Feedback.
Die Abfragen erreichen verschachtelte Daten wie fehlgeschlagene Tool-Aufrufe, niedrige Scores und Daumen-runter-Feedback.
Jede Abfrage deckt bis zu 31 Tage und bis zu 100 Bedingungen ab, mit bis zu 8 Filtern auf Spans, Scores oder Feedback.
Verfügbar über die Mastra-Plattform, das lokale Studio, die CLI (ab [email protected]), das Client SDK (ab @mastra/[email protected]) und HTTP-Endpunkte.
Selbst gehostete Projekte benötigen DuckDB, PostgreSQL oder ClickHouse als Observability-Speicher.

Was Trace-Abfragen leisten

Laut Mastra können Nutzerinnen und Nutzer in der Plattform und im lokalen Studio Traces jetzt nach Feldern wie Zeit, Primitive-Name, Agent- oder Workflow-ID, Status, Score und Feedback filtern. Dieselben Abfragen lassen sich über die CLI, das Mastra Client SDK und HTTP-Observability-Endpunkte aufbauen. Damit kann sie auch ein Coding-Agent ausführen.

Einen Anwendungsfall hebt Mastra besonders hervor: Ein Coding-Agent soll nach Traces suchen, die mit einem Fehler endeten oder fehlgeschlagen sind, oder nach langsamen Modellaufrufen, und diese anschließend beheben.

Abfragen auf Trace-Feldern der obersten Ebene decken ab, wann ein Trace lief, welcher Agent ihn ausgeführt hat und ob er erfolgreich war. Mastra weist darauf hin, dass die Details, die ein Problem erklären, oft tiefer liegen, etwa in einem fehlgeschlagenen Tool-Aufruf, einem niedrigen Score oder Daumen-runter-Feedback. Trace-Abfragen können auf diese verschachtelten, detaillierten Informationen zugreifen und so ein genaueres Bild davon liefern, was passiert ist.

Grenzen und unterstützte Speicher

Jede Abfrage deckt einen Zeitraum von bis zu 31 Tagen ab und kann bis zu 100 Bedingungen kombinieren. Zu den nutzbaren Feldern zählen entityName, environment, spans.model, scores.score und feedback.value. Bis zu 8 Filter können auf das Innere eines Traces zielen (Spans, Scores oder Feedback) statt auf Felder des Traces selbst.

Das Beispiel in der Ankündigung kombiniert drei Bedingungen: Produktionsumgebung, eine Dauer von mehr als 5000 ms und mindestens ein Span vom Typ tool_call, der einen Fehler aufweist. Die Ergebnisse sind nach Startzeit sortiert, die neuesten zuerst, mit einem Seitenlimit von 25.

Trace-Abfragen funktionieren auf der Mastra-Plattform und in selbst gehosteten Mastra-Projekten, in denen storage.observability DuckDB, PostgreSQL oder ClickHouse nutzt.

Drei Wege, eine Abfrage auszuführen

Anfragen benötigen ein Plattform-Zugriffstoken und eine Projekt-ID. Nutzer müssen die Observability-Basis-URL für ihre Region wählen: https://observability.mastra.ai für die USA oder https://observability.eu.mastra.ai für die EU.

Mastra CLI: Installation oder Update mit npm install -g mastra@latest. Erforderlich ist [email protected] oder neuer. Der Befehl mastra api trace query liest MASTRA_PLATFORM_ACCESS_TOKEN und MASTRA_PROJECT_ID aus der Umgebung.
Mastra Client SDK: @mastra/client-js@latest installieren, was Version 1.44.0 oder neuer erfordert, und queryTraces() auf einem MastraClient aufrufen.
Observability-Endpunkte: eine POST-Anfrage an den Trace-Query-Endpunkt senden, mit Token und Projekt-ID in den Headern.

Mastras Beispiele suchen jeweils nach Agent-Traces der letzten 7 Tage, die mit einem Fehler endeten, und verwenden dafür die Bedingungen entityType gleich agent und status gleich error.

Verfügbare Felder und Operatoren

Bedingungen lassen sich mit and, or und not verknüpfen. Zu den Feldern auf Trace-Ebene gehören traceId, threadId, userId, entityName, environment, status, durationMs, tags und Metadaten-Schlüssel. Span-Abfragen mit spans.some und spans.none umfassen Felder wie name, spanType, model, provider, status und error. Scores und Feedback haben eigene some- und none-Formen, mit Feldern wie scorerId, score, feedbackType, value und comment.

Zu den Operatoren zählen eq, ne, in, notIn, lt, lte, gt, gte, exists und notExists, dazu includes für Tags und matches für Span-Namen und Feedback-Kommentare. Außerdem gibt es Paginierungsoptionen sowie die Discovery-Helfer getTraceQueryFields() und getTraceQueryValues().

Was das für Nutzer bedeutet

Für Teams, die Mastra-Agenten und -Workflows betreiben, lässt sich damit eine große Menge an Traces auf genau die Läufe eingrenzen, in denen ein Tool fehlschlug oder ein Modellaufruf langsam war, ohne manuelles Durchsuchen. Weil dieselben Abfragen über CLI, SDK und HTTP verfügbar sind, lassen sie sich skripten oder, wie Mastra es beschreibt, an einen Coding-Agenten übergeben. Auch selbst hostende Nutzer können die Funktion verwenden, sofern ihr Observability-Speicher DuckDB, PostgreSQL oder ClickHouse ist.