Trace Queries érkezett a Mastrához, mélyebben kereshetővé válnak a nyomok

Összetett feltételek a trace-ek kereséséhez

A Mastra platform és a helyi Studio mostantól olyan mezők alapján is szűrhető, mint az időpont, a primitív neve, az agent vagy workflow azonosítója, az állapot, a pontszám és a visszajelzés. Ugyanezek a lekérdezések a Mastra CLI-n, a Mastra Client SDK-n és a HTTP-alapú megfigyelhetőségi végpontokon keresztül is összeállíthatók.

A Trace Queries jellemzően magán a trace-en keres mezőket. Ilyen például, hogy mikor futott le, melyik agent indította, és sikeres volt-e. A Mastra közleménye szerint azonban egy hiba okát gyakran egy mélyebben található részlet mutatja meg, például egy sikertelen eszközhívás, alacsony pontszám vagy negatív visszajelzés. A lekérdezések ezekhez a belső adatokhoz is hozzáférnek.

A feltételek az and, or és not logikai műveletekkel kombinálhatók. Egy lekérdezés legfeljebb 31 napos időtartományt fedhet le, és legfeljebb 100 feltételt tartalmazhat. A trace belső részeire, vagyis a spans, scores és feedback elemekre legfeljebb 8 szűrő vonatkozhat.

Hibás és lassú futások azonosítása

A keresés többek között az entityName, environment, spans.model, scores.score és feedback.value mezőkre épülhet. A példaként bemutatott lekérdezés a production környezetben futó, 5000 milliszekundumnál hosszabb trace-eket keresi, amelyekben hibás eszközhívás szerepel. Az eredményeket a kezdési idő szerint csökkenő sorrendbe rendezi, és 25 találatra korlátozza.

A Mastra szerint a kódoló ügynök is lekérdezheti a hibával leállt vagy sikertelen trace-eket, illetve a lassú modellhívásokat, majd ezek alapján javíthatja a problémákat. A Trace Queries így a hibakeresési folyamat részeként használható, a hibákat és a felhasználói visszajelzéseket egyaránt figyelembe véve.

A kereshető adatok között megtalálható többek között a trace azonosítója, a futás időtartama, a státusz, a környezet, a címkék és a metaadatok. A spaneknél a modell, a szolgáltató, a hiba, az időtartam és az állapot szűrhető. A pontszámokhoz tartozik például a pontszám forrása és értéke, a visszajelzéseknél pedig a típus, az érték, a megjegyzés és a forrás.

CLI, SDK és megfigyelhetőségi végpontok

A Trace Queries három módon futtatható: a Mastra Client SDK-val, a Mastra CLI-vel és az observability végpontokon keresztül. A bemutatott példák mindegyike az elmúlt 7 napban futott, hibával végződött agent trace-eket keresi.

A CLI használatához a Mastra közleménye szerint a globálisan telepített vagy frissített mastra csomag 1.30.0-s vagy újabb verziója szükséges. A lekérdezéshez a mastra api trace query parancs használható. A CLI a MASTRA_PLATFORM_ACCESS_TOKEN és a MASTRA_PROJECT_ID környezeti változókat olvassa ki.

A Client SDK esetében a queryTraces() metódus és az @mastra/client-js csomag használható. Ehhez a csomag 1.44.0-s vagy újabb verziójára van szükség. A közvetlen HTTP-kérés POST metódussal küldhető a trace query végpontra, a hozzáférési tokent és a projektazonosítót pedig a fejlécekben kell megadni.

Platform és saját üzemeltetésű projektek

A Trace Queries a Mastra platformon, valamint a saját üzemeltetésű Mastra-projekteken is működik, ha az storage.observability DuckDB, PostgreSQL vagy ClickHouse használatára van beállítva. A lekérdezésekhez platform-hozzáférési tokenre és projektazonosítóra van szükség, ezeket minden kérésnél továbbítani kell.

A Mastra két megfigyelhetőségi alapcímet ad meg. Az Egyesült Államok régiójához a https://observability.mastra.ai, az európai régióhoz a https://observability.eu.mastra.ai cím tartozik. A fejlesztők külön referenciaanyagokat kapnak a haladó trace-lekérdezésekhez, a Client SDK-hoz, a CLI-hez, a platform régióihoz és a megfigyelhetőség beállításaihoz.

A bejelentés 2026. október 14-én jelent meg. A felhasználók számára a funkció azt jelenti, hogy a Mastra-rendszerek működése célzottabban vizsgálható, a keresés pedig a teljes trace mellett annak részletes belső eseményeire is kiterjedhet.