Zum Hauptinhalt springen
Durchsuchen Sie Log-Zeilen mit der Public API (V2). Dies ist der Weg, Logs programmatisch abzufragen, einschließlich strukturierter (JSON-)Logdaten. Die GraphQL-API stellt keine Log-Zeilen bereit.
Wenn Sie einen KI-Agenten oder Assistenten erstellen, stellt AppSignal MCP die Logsuche und andere Monitoring-Daten direkt für Agenten bereit, ohne dass Sie diese API selbst aufrufen müssen.

Site- und Quellen-IDs finden

Eine Logsuche benötigt eine site_id und eine oder mehrere source_ids. Beide erscheinen in der URL einer Log-Quelle in AppSignal. Öffnen Sie eine Log-Quelle und lesen Sie sie aus dem Pfad ab:

Log-Zeilen durchsuchen

Alle Felder von Request und Antwort finden Sie in der Referenz Log-Zeilen durchsuchen. Die Anfrage nimmt eine site_id, die zu durchsuchenden source_ids, eine query und ein pagination-Objekt entgegen. Geben Sie mindestens eine Quellen-ID an: Eine leere source_ids-Liste gibt keine Zeilen zurück. Eine leere query trifft jede Zeile. Siehe Abfragesprache. from ist standardmäßig der Beginn Ihrer Log-Aufbewahrung, to standardmäßig der aktuelle Zeitpunkt. pagination nimmt per_page (Zahl), order (ASC oder DESC) und einen cursor mit time und id entgegen. Setzen Sie beide für die erste Seite auf null. Um die nächste Seite abzurufen, senden Sie timestamp und id der letzten erhaltenen Zeile als cursor.time und cursor.id. Ohne die id werden Zeilen mit demselben Zeitstempel übersprungen.

Beispielanfrage

Der Endpunkt gibt ein Array von Log-Zeilen zurück. Die strukturierten Daten jeder Zeile liegen in ihrem json-Feld, als JSON-kodierter String. Um stattdessen Zeilen zu zählen oder den Durchschnitt eines Felds zu bilden, fragen Sie Log-Metriken ab.
Strukturierte Felder wie status_code, path oder detail liegen im json-Feld. Fragen Sie sie über ihren exakten Schlüssel ab, wie er im JSON Ihres Logs erscheint (zum Beispiel status_code=401 oder detail.message:"required").

Abfragesprache

Der query-String unterstützt boolesche Logik über Felder von Log-Zeilen und den strukturierten json-Body.

Operatoren

String-Operatoren (=, !=, :, !:) vergleichen beide Seiten als Strings. Numerische Operatoren (>, >=, <, <=) wandeln beide Seiten in eine Zahl um; kann ein Wert nicht als Zahl geparst werden, wird diese Log-Zeile übersprungen.

Ausdrücke kombinieren

  • AND / OR: severity=error AND hostname:web oder severity=info OR severity=warn.
  • Implizites AND: Ein Leerzeichen zwischen Ausdrücken bedeutet AND. severity=error hostname:web entspricht severity=error AND hostname:web.
  • Verschachtelung mit Klammern: message:"API request" AND (severity=info OR severity=warn).
  • Vorrang: AND bindet stärker als OR.
Jeder Operator kann innerhalb einer OR-Gruppe verwendet werden, nicht nur Gleichheit — zum Beispiel message:"API request" AND (user.id>1000 OR user.email:"example.com").

Felder

Gegeben sei eine Log-Zeile mit diesem JSON-Body:
  • Basisfelder: message, severity, hostname und group passen auf die obersten Felder der Log-Zeile.
  • Verschachteltes JSON: Verwenden Sie Punktnotation, um in den json-Body zu greifen, etwa status_code=200 oder user.id=12345.
  • JSON-Arrays: Indizieren Sie Array-Elemente, etwa user.roles.0=admin.
  • Escapte Punkte: Um einen wörtlichen Punkt in einem Schlüsselnamen zu treffen, escapen Sie ihn. user.location\.country=US trifft den Schlüssel location.country innerhalb von user, statt eines verschachtelten country-Objekts.
  • Standardfeld: Ein nackter Begriff ohne Feld trifft message mit dem contains-Operator. timeout entspricht message:timeout.
Referenzieren Sie ein Feld direkt über seinen Namen im JSON Ihres Logs, ohne Typsuffix. Siehe alte Abfragesyntax, wenn Sie ältere Abfragen haben.

Werte in Anführungszeichen

Setzen Sie Werte, die Leerzeichen oder Klammern enthalten, in doppelte Anführungszeichen. Andernfalls trennt das Leerzeichen den Wert in separate Ausdrücke, die durch implizites AND verbunden werden.
Nur doppelte Anführungszeichen werden erkannt. Innerhalb eines zitierten Werts escapen Sie ein Anführungszeichen mit \" und einen Backslash mit \\. Zum Beispiel trifft message:"value with \"quotes\"" den Text value with "quotes".

Alte Abfragesyntax

Ältere Abfragen speicherten Attribute als typisierte Felder, sodass sie attributes. voranstellen, ein Typsuffix (_string, _int) anhängen und für mehrere Werte eine [ ]-Liste verwenden mussten. Die aktuelle Abfragesprache entfernt alle drei — referenzieren Sie Felder direkt und verwenden Sie OR anstelle einer Liste:
Die API liest die alte Syntax nicht mehr, lehnt sie aber auch nicht mehr ab. attributes. ist jetzt ein gewöhnlicher Pfad in das JSON Ihres Logs. Daher sucht attributes.user_id_int=12345 nach einem Schlüssel user_id_int innerhalb eines attributes-Objekts. Ein Filter in der alten attributes.-Form trifft nichts, statt einen Fehler zurückzugeben. Wenn Ihre Logs ein attributes-Objekt enthalten, können Sie nach dessen Feldern filtern, etwa attributes.user_id=12345.