Mastra führt Span-Abfragen ein, um Spans über alle Traces hinweg zu filtern und zu gruppieren

Von ganzen Traces zu einzelnen Spans

Bisher konnten Trace-Abfragen zwar nach Details tief im Trace filtern, etwa nach einem fehlgeschlagenen Tool-Aufruf, lieferten aber den gesamten Trace zurück. Laut Mastra mussten fehlgeschlagene Tool-Aufrufe deshalb gefunden werden, indem man jeden Trace einzeln öffnete und prüfte. Span-Abfragen arbeiten feingranularer: Sie durchsuchen jeden Trace und geben nur die Spans zurück, die passen.

In der Mastra-Plattform und in Studio können Nutzer im Tab „Spans“ unter anderem nach Zeitraum, Span-Typ, Span-Name, Status, Fehler und Dauer filtern. Ein Coding-Agent kann laut Mastra dieselben Abfragen über die CLI, das Client SDK und die HTTP-Endpunkte aufbauen, um Probleme zu finden und zu beheben.

Spans gruppieren und aggregieren

Span-Abfragen können über die passenden Spans hinweg auch gruppieren oder aggregieren, etwa mit Kennzahlen wie Anzahl, Fehlerquote und Latenz. Mastra empfiehlt, damit zu erkennen, welches Tool fehlschlägt oder langsam läuft, oder die Tool-Latenz im Zeitverlauf zu verfolgen. Anschließend lassen sich mit denselben Filtern Span-Abfragen ausführen, um die problematischen Aufrufe zu untersuchen.

Die dokumentierten Grenzen lauten:

• Jede Abfrage kann bis zu 100 Bedingungen kombinieren, mit Feldern wie spanType, entityName, status, durationMs und parentEntityName.
• Span-Abfragen liefern bis zu 1.000 Spans pro Seite.
• Span-Gruppen können nach bis zu 2 Dimensionen gruppieren, über einen timeRange von bis zu 365 Tagen.

Die Funktion läuft auf der Mastra-Plattform sowie in selbst gehosteten Mastra-Projekten, in denen storage.observability DuckDB, PostgreSQL oder ClickHouse nutzt. Teams, deren Trace-Daten außerhalb von Mastra liegen, können ihre bestehende Historie per Trace-Import übernehmen.

Vier Wege, eine Abfrage auszuführen

Span-Abfragen benötigen ein Plattform-Zugriffstoken und eine Projekt-ID, die mit jeder Anfrage gesendet werden. Die Basis-URL hängt von der Region des Projekts ab: https://observability.mastra.ai für die USA und https://observability.eu.mastra.ai für die EU.

Mastras Beispiele gruppieren Tool-Aufrufe der letzten 7 Tage nach Tool und suchen dann die Tool-Aufrufe, die mit einem Fehler endeten.

• Mastra CLI: erfordert [email protected] oder neuer. Der Befehl mastra api span aggregate liefert Aufrufanzahl, Fehlerquote und p95-Latenz für jedes Tool, und mastra api span query findet Tool-Aufrufe, die mit einem Fehler endeten. Die CLI liest MASTRA_PLATFORM_ACCESS_TOKEN und MASTRA_PROJECT_ID aus der Umgebung.
• Mastra-Plattform und Studio: Der Tab „Spans“ bietet die Filter.
• Mastra Client SDK: erfordert @mastra/[email protected] oder neuer. aggregateSpans() liefert Aufrufanzahl, Fehlerquote und p95-Latenz pro Tool, mit den größten Problemfällen zuerst. Mit einem Intervall wie 1d lässt sich die Latenz im Zeitverlauf anhand von p50, p95 und p99 verfolgen. querySpans() liefert die fehlgeschlagenen Tool-Aufrufe.
• Observability-Endpunkte: An die Endpunkte für Span-Gruppen und Span-Abfragen kann eine POST-Anfrage gesendet werden, mit Token und Projekt-ID in den Headern.

Was das für Teams bedeutet, die Agenten entwickeln

Für Teams, die Agenten auf Mastra betreiben, verlagert sich das Debugging damit vom einzelnen Prüfen von Traces hin zum direkten Abfragen der Spans. Eine aggregierte Ansicht kann zeigen, welches Tool die höchste Fehlerquote oder Latenz hat, und eine anschließende Abfrage mit denselben Filtern liefert die konkreten fehlgeschlagenen Aufrufe. Weil dieselben Abfragen über CLI, SDK und HTTP-Endpunkte bereitstehen, können sie sowohl Coding-Agenten als auch Menschen in der Studio-Oberfläche ausführen.

Für alle Konfigurationsoptionen verweist Mastra auf die Observability-Referenz des Client SDK, die Referenz zu aggregierten Spans, die CLI-Referenz zu mastra api span query und die Observability-Dokumentation der Plattform.