422 und validation_failed ab, sofern die Matrix
nichts anderes angibt. Kurzformen wie project, trace und user sind keine
Query-Schlüssel. Übertragen Sie einen Filter nicht von einer Route auf eine
andere.
Gefilterte Anfrage aufbauen
Setzen Sie den Query-String hinter den Pfad. Verwenden Sie--data-urlencode, damit reservierte Zeichen sicher bleiben. Diese Anfrage
liest kritische Logs eines Projekts aus den letzten 24 Stunden:
- Wählen Sie das Projekt mit
project_idoderproject_idsaus. - Ergänzen Sie einen Zeitraum mit
sinceund optionaluntil. - Ergänzen Sie Filter für Dienst, Release, Umgebung, Status oder ein bestimmtes Signal.
- Setzen Sie
limitfür eine kleinere Seite. - Ergänzen Sie Cursor-Felder erst, wenn eine Cursor-Antwort sie liefert.
GET /api/logs den Wert status=active, wenn Sie status weglassen.
Filtermatrix
Schlüssel in der Spalte „Erforderlich“ müssen in der Anfrage stehen. Alle anderen Schlüssel sind optional.
Bei der Issue-Untersuchung ist
selection gleich first, latest oder
recommended. Senden Sie selection oder occurrence_id, nicht beides.
Beide brauchen eine response_version von 2 bis 13. Ab Version 2 und ohne
Auswahl verwendet LogBrew recommended. Eine occurrence_id erhalten Sie
über GET /api/telemetry/issues/{issue_id}/events.
Die POST-Routen für Analysen nehmen einen JSON-Body an. Siehe
Produktanalysen.
Gemeinsame und signalspezifische Filter
service_name, release und environment grenzen jede Telemetrie-Liste
ein. Verwenden Sie genau die Werte, die Ihr SDK sendet.
Manche Filter gehören zu einem bestimmten Signal:
- Logs akzeptieren
search,trace_id,severityundattribute_filters. - Logs akzeptieren
status:active(Standard),ignoredoderall.ignoredwählt die Logs aus, die eine Log-Regel in der aktiven Ansicht ausblendet. - Issues akzeptieren den Issue-
status:unresolved,resolvedoderarchived.ignoredist ein älterer Name fürarchivedund wählt dieselben Issues aus. - Issues akzeptieren
severity:info,warning,errorodercritical. - Issues akzeptieren
priority:high,mediumoderlow. - Issues akzeptieren
assignee:mefür die Issues, die dem angemeldeten Konto zugewiesen sind,nonefür Issues ohne Zuweisung,my_teamsfür die Issues Ihrer Teams, eine Nutzer-ID oderteam:<team_id>. - Aktionen und Metriken akzeptieren
name. - Aktionen akzeptieren
distinct_id. - Traces akzeptieren den Trace-
statusundmin_duration_ms. - Bereitstellungen akzeptieren
status:succeededoderfailed.
severity-Filter für Logs und Issues vergleichen den effektiven
Schweregrad. Hat eine Regel den Schweregrad geändert, verwendet der Filter den
Wert der Regel. Siehe
Werte für den Schweregrad.
Zeitraum
since akzeptiert eine positive ganze Zahl von Stunden oder Tagen, zum
Beispiel 24h oder 7d, oder einen RFC3339-Zeitstempel. Eine kompakte
Dauer bezieht sich auf den Zeitpunkt der jeweiligen Anfrage.
until akzeptiert nur einen RFC3339-Zeitstempel. Es ist ein exklusiver
Endzeitpunkt: Eine Zeile genau zum Zeitpunkt until ist nicht im Ergebnis.
since ist inklusiv. Zum Beispiel wählen since=2026-10-01T00:00:00Z und
until=2026-10-02T00:00:00Z genau 1 vollen Tag aus. LogBrew vergleicht
Zeitpunkte auf die Millisekunde genau.
until muss später sein als since. Ist das nicht so, oder ist until kein
RFC3339-Zeitstempel, schlägt die Anfrage mit 422 und validation_failed
fehl.
Wählen Sie für einen Lesezugriff über mehrere Seiten einen festen
RFC3339-Startzeitpunkt, und behalten Sie ihn auf jeder Seite bei. Behalten Sie
auch dasselbe until auf jeder Seite bei.
Diese Anfrage liest Fehler-Logs eines Tages:
Die Bereitstellungsliste verwendet andere Zeitregeln. Ihre Werte
since und
until akzeptieren nur RFC3339-Zeitstempel, und beide sind inklusiv. Sie
vergleichen den Zeitpunkt, zu dem die Bereitstellung abgeschlossen wurde.Antwortversion für Issues
Die Issue-Liste und die Issue-Details akzeptierenresponse_version=1,
response_version=2, response_version=3 oder response_version=4. Version 1 ist der Standard.
Ein anderer Wert schlägt mit 422 und validation_failed fehl.
- Version 1 zeigt den archivierten Zustand als
ignored. Sie zeigt keine Priorität. - Version 2 zeigt den archivierten Zustand als
archived. Sie ergänztpriorityundpriority_source. - Version 3 hat alle Felder von Version 2. Sie ergänzt
assignee. - Version 4 hat alle Felder von Version 3.
assigneehattype:useroderteam.
status=archived, priority und assignee. Siehe
die Issue-Antwort.
Filter für den Schweregrad
Verwenden Sieseverity=info|warning|error|critical bei GET /api/logs. Der
ältere Schlüssel level ist ein Alias für Kompatibilität. Beide Schlüssel
akzeptieren die kanonischen Werte und die Aliasse trace, debug, warn
und fatal. LogBrew wandelt einen Alias vor dem Vergleich in seinen
kanonischen Wert um.
Sendet eine Anfrage sowohl severity als auch level, normalisiert LogBrew
zuerst beide. Widersprüchliche Werte werden abgelehnt mit:
Trace-Filter
Bei der Trace-Suche iststatus gleich error oder ok. Lassen Sie den
Wert weg, um beides einzuschließen. min_duration_ms muss null oder größer
sein. Der Wert gilt nur für die Trace-Suche.
Diese Anfrage findet Fehler-Traces, die mindestens 500 Millisekunden gedauert
haben:
trace_id per
Prozent-Kodierung als Pfadsegment. Senden Sie den Wert nicht als
Query-Schlüssel.
Projektbereich
Verwenden Sieproject_id=<project-uuid>, um ein Projekt zu lesen. Auf den
Routen, die in der Matrix project_ids aufführen, verwenden Sie
project_ids=<uuid>,<uuid> für eine exakte Menge von 2 bis 50 Projekten.
Lassen Sie auf diesen Routen beide Schlüssel weg, um jedes Projekt zu lesen,
das das Konto lesen darf. Eine Route, die project_id erfordert, akzeptiert
nur 1 Projekt.
422 und validation_failed ab:
- Eine Anfrage, die sowohl
project_idals auchproject_idsenthält. - Einen Wert für
project_idsmit weniger als 2 oder mehr als 50 IDs. - Eine doppelte ID oder eine ID, die keine UUID ist.
project_ids ein Projekt, das das Konto nicht lesen darf,
schlägt die Anfrage mit 404 und not_found fehl. Entfernen Sie diese ID
nicht einfach, um weiterzumachen. Bitten Sie die Person, eine neue Menge
auszuwählen.
Behalten Sie denselben Projektbereich auf jeder Cursor-Seite bei. Entfernen
Sie den Projektfilter nicht nach einem leeren Ergebnis, denn damit stellen Sie
eine andere Frage.
Zeitreihen in Zeitfenstern
GET /api/telemetry/metrics/series liefert eine Metrik in Zeitfenstern.
GET /api/telemetry/summary/volume liefert die Anzahl der Signale in
Zeitfenstern. Für beide Routen gelten diese Regeln:
sinceist erforderlich.untilist optional, Standard ist der Zeitpunkt der Anfrage.- Der Bereich von
sincebisuntilumfasst höchstens 31 Tage. intervalistauto,1m,5m,15m,1h,6hoder1d. Standard istauto. Ein Intervall, das mehr als 500 Zeitfenster ergibt, schlägt fehl.service_name,releaseundenvironmentsind exakte Filter.
name der exakte Metrikname aus
GET /api/telemetry/metrics. group_by ist none, service_name,
release oder environment. series_limit liegt zwischen 1 und 20.
Beim Signalvolumen darf until nicht in der Zukunft liegen, und
response_version ist nur 1.
Log-Attribute filtern
MitGET /api/logs/attributes finden Sie die Attributpfade und Typen, die Sie
durchsuchen können. Senden Sie dann attribute_filters an GET /api/logs.
Beide Anfragen brauchen since.
Attributkatalog lesen
Diese Anfrage findet in einem Projekt numerische Pfade, diestatus
enthalten:
type ist string, number oder boolean. observed_count ist die Anzahl
der Logs im Bereich, die diesen Pfad und Typ haben. last_seen_at ist der
Zeitpunkt des neuesten davon. Ein Log kann viele Pfade haben. Addieren Sie die
Anzahlen nicht, um eine Anzahl von Logs zu erhalten.
coverage zeigt, welche Logs ein Attributfilter durchsuchen kann:
Die 3 Gruppen ergeben zusammen
total_logs. type, search und der Cursor
des Katalogs ändern die Abdeckung nicht. Eine leere attributes-Liste
bedeutet nicht, dass total_logs null ist.
Der Katalog hat keinen Schlüssel status. Sein Filter für den Schweregrad
vergleicht den erfassten Schweregrad, nicht den effektiven.
search ist ein Teilstring des Pfads mit 1 bis 128 Byte ohne Steuerzeichen.
limit legt die Anzahl der Attribute pro Seite fest.
Katalog weiterlesen
Der Katalog verwendet nichtpagination=cursor. Wiederholen Sie jeden Filter,
und kopieren Sie alle 3 Felder aus next_cursor:
Hören Sie auf, wenn
next_cursor gleich null ist.
Typisierten Filter anwenden
Kopieren Sie Pfad und Typ aus dem Katalog. Pfade verwenden die Syntax von JSON Pointer, keine Schlüssel mit Punkten. Lassen Sie jedes Escape~0 oder
~1 im Pfad unverändert.
Diese Anfrage liest Logs, deren numerischer Antwortstatus 500 oder höher ist:
attribute_filters ist ein JSON-Array mit 1 bis 4 Filtern. Ein Log muss zu
jedem Filter passen. Jeder Filter hat path, type, operator und value.
Der JSON-Typ von value muss zu type passen: Die Zahl 500 ist nicht der
String "500".
ne passt nur zu Logs, die den Pfad haben. Ein Log ohne den Pfad passt nicht
zu ne. Bei string ist case_sensitive optional, Standard ist false.
LogBrew lehnt "case_sensitive": true für number und boolean ab.
Es gelten diese Limits:
- Das JSON-Array hat höchstens 4.096 Byte.
- Ein String-Wert hat höchstens 1.024 Byte.
containsundstarts_withbrauchen einen nicht leeren String.- Eine Zahl muss endlich sein und zwischen -9.007.199.254.740.992 und 9.007.199.254.740.992 liegen.
attribute_filters erscheinen. Zur
Log-Antwort siehe
Log-Antwort.
Attributfehler korrigieren
Jeder Fehler unten liefert422 mit validation_failed:
Korrigieren Sie die Anfrage, bevor Sie sie wiederholen. Entfernen Sie keinen
Filter, denn das ändert das Ergebnis.
Cursor-Paginierung
Der Cursor-Modus muss aktiv eingeschaltet werden. Ohne ihn liefern Listen-Routen ein reines Array. Senden Sie für die erste Seitepagination=cursor ohne Cursor-Felder. Wiederholen Sie für jede weitere Seite
jeden Filter, und senden Sie alle Cursor-Felder vollständig:
Übertragen Sie die gelieferten Felder von
next_cursor in die nächste
Anfrage:
next_cursor.timewird zucursor_time.next_cursor.idwird zucursor_id.- Bei Traces wird
next_cursor.trace_idzucursor_trace_id. - Bei Releases setzen Sie
cursor_vor jeden gelieferten Feldnamen. Zum Beispiel wirdnext_cursor.releasezucursor_release.
next_cursor gleich null ist. Berechnen Sie keinen
Cursor aus der letzten Zeile. Der Release-Cursor ändert die ausgewählten
Projekte nicht. Behalten Sie das ursprüngliche project_id oder
project_ids bei.
limit legt die Seitengröße fest. Eine Seite kann weniger Zeilen enthalten.
Diese Routen akzeptieren weder page noch page_number.
Auf den meisten Routen setzt LogBrew ein
limit über dem Maximum auf das
Maximum herab. Die Bereitstellungsliste lehnt ein limit außerhalb von 1 bis 100
mit 422 ab. Die Bereitstellungsliste liefert immer ein Seitenobjekt mit
next_cursor, auch ohne pagination=cursor.
LogBrew lehnt diese Anfragen mit 422 und validation_failed ab:
- Einen Wert für
paginationaußercursor. - Cursor-Felder ohne
pagination=cursor. - Unvollständige Cursor-Felder.
- Einen Wert für
cursor_time, der kein RFC3339-Zeitstempel ist.
Leeres Ergebnis diagnostizieren
Eine leere Liste bedeutet, dass keine Zeile zu allen Filtern passt. Über andere Signale sagt sie nichts aus. Prüfen Sie die Anfrage in dieser Reihenfolge:- Prüfen Sie die Projekt-ID.
- Entfernen Sie optionale Filter einzeln.
- Erweitern Sie
since, wenn das erwartete Ereignis älter ist. Entfernen Sieuntil, oder verschieben Sie es nach hinten, wenn das erwartete Ereignis neuer ist. - Vergleichen Sie
service_name,releaseundenvironmentmit den Werten, die Ihr SDK sendet. - Ergänzen Sie bei Logs
status=all, wenn eine Log-Regel das erwartete Log ausblenden kann. - Prüfen Sie, ob die Route jeden Filter akzeptiert.
Abgelehnte Abfrage beheben
Eine abgelehnte Abfrage liefert den Standard-Fehlerumschlag. Ein unbekannter Schlüssel oder ein Wert mit falschem Typ liefert422:
- Ersetzen Sie eine Kurzform durch den Schlüssel aus der Filtermatrix.
- Senden Sie jedes Cursor-Feld zum Weiterlesen, das die Route braucht.
- Entfernen Sie Cursor-Felder aus der Anfrage für die erste Seite.
- Verwenden Sie nur eine Projektauswahl.
- Ersetzen Sie einen nicht unterstützten Schweregrad oder Trace-Status durch einen kanonischen Wert.
