Logs abfragen - AppSignal Documentation

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:

https://appsignal.com/<organization>/sites/<SITE_ID>/logs/sources/<SOURCE_ID>

Log-Zeilen durchsuchen

POST /api/v2/logs/lines

Request-Body

Feld	Typ	Erforderlich	Beschreibung
`site_id`	string	Ja	Abzufragende Site.
`source_ids`	string[]	Ja	Log-Quellen-IDs, die durchsucht werden sollen. Mindestens eine ist erforderlich.
`query`	string	Ja	Abfragestring, der Log-Zeilen filtert. Siehe Abfragesprache.
`use_expressions`	boolean	Nein	Wenn `true`, wird `query` mit der ausdrucksbasierten Abfragesprache geparst.
`from`	string (ISO 8601)	Nein	Start des Zeitbereichs. Standardwert ist die untere Grenze der Aufbewahrung.
`to`	string (ISO 8601)	Nein	Ende des Zeitbereichs. Standardwert ist die aktuelle Zeit.
`pagination`	object	Ja	Paginierungs-Cursor und -Richtung (siehe folgenden Abschnitt).

Setzen Sie use_expressions auf true, um die auf dieser Seite dokumentierte ausdrucksbasierte Abfragesprache zu verwenden. pagination nimmt per_page (Zahl), order (ASC oder DESC) und einen cursor mit einem time-Feld (ein ISO-8601-Zeitstempel oder null für die erste Seite) entgegen. Um die nächste Seite abzurufen, senden Sie den Zeitstempel der letzten erhaltenen Zeile als cursor.time der nächsten Anfrage.

Beispielanfrage

curl --request POST \
  --url "https://appsignal.com/api/v2/logs/lines" \
  --header "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  --header "Content-Type: application/json" \
  --data @body.json

{
  "site_id": "YOUR-SITE-ID",
  "source_ids": ["YOUR-LOG-SOURCE-ID"],
  "query": "severity=error status_code=401",
  "use_expressions": true,
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T23:59:59Z",
  "pagination": {
    "per_page": 100,
    "order": "DESC",
    "cursor": { "time": null }
  }
}

Antwort

Der Endpunkt gibt ein Array von Log-Zeilen zurück. Jede Zeile enthält diese Felder:

Feld	Typ	Beschreibung
`id`	string	Bezeichner der Log-Zeile.
`timestamp`	string (ISO 8601)	Zeitpunkt, zu dem die Log-Zeile aufgezeichnet wurde.
`source_id`	string	Log-Quelle, zu der die Zeile gehört.
`severity`	string	Schweregrad, etwa `info` oder `error`.
`message`	string	Der Log-Nachrichtentext.
`hostname`	string	Host, der die Zeile erzeugt hat.
`group`	string	Log-Gruppe.
`json`	string	Der rohe strukturierte (JSON-)Body der Log-Zeile, sofern verfügbar.
`attributes`	object	Veraltete typisierte Schlüssel-Wert-Attribute. Wird ausgemustert — bevorzugen Sie `json`.

Strukturierte Felder wie status_code, path oder detail liegen im json-Feld, nicht in attributes. 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

Wenn use_expressions true ist, unterstützt der query-String boolesche Logik über Felder von Log-Zeilen und den strukturierten json-Body.

Operatoren

Operator	Name	Verhalten
`=`	Gleich	Exakte Übereinstimmung.
`!=`	Ungleich	Exakte Nicht-Übereinstimmung.
`:`	Enthält	Teilstring-Übereinstimmung.
`!:`	Enthält nicht	Teilstring-Nicht-Übereinstimmung.
`>`	Größer als	Numerischer Vergleich.
`>=`	Größer oder gleich	Numerischer Vergleich.
`<`	Kleiner als	Numerischer Vergleich.
`<=`	Kleiner oder gleich	Numerischer Vergleich.

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:

{
  "message": "API request completed",
  "severity": "info",
  "duration": 156.7,
  "status_code": 200,
  "user": {
    "id": 12345,
    "roles": ["admin", "developer"],
    "location.country": "US"
  }
}

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.

Sie müssen einem Feld kein attributes. voranstellen oder ein Typsuffix anhängen, um es abzufragen — referenzieren Sie es direkt über den Namen. 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.

message:"hello world"           matches message containing "hello world"
message:hello world             parsed as message:hello AND message:world
severity=error message:"oh no"  severity equals error AND message contains "oh no"

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:

message:"API request" attributes.user_id_int=12345 severity=[info, warn]

message:"API request" user.id=12345 (severity=info OR severity=warn)

Eine Abfrage, die noch die alte Syntax verwendet, gibt einen 422 mit dem Fehler-Slug legacy_log_query_syntax zurück.

​Site- und Quellen-IDs finden

​Log-Zeilen durchsuchen

​Request-Body

​Beispielanfrage

​Antwort

​Abfragesprache

​Operatoren

​Ausdrücke kombinieren

​Felder

​Werte in Anführungszeichen

​Alte Abfragesyntax

Site- und Quellen-IDs finden

Log-Zeilen durchsuchen

Request-Body

Beispielanfrage

Antwort

Abfragesprache

Operatoren

Ausdrücke kombinieren

Felder

Werte in Anführungszeichen

Alte Abfragesyntax