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: 
https://appsignal.com/<organization>/sites/<SITE_ID>/logs/sources/<SOURCE_ID>

​
Log-Zeilen durchsuchen

POST /api/v2/logs/lines

​
Request-Body

FeldTypErforderlichBeschreibung
site_idstringJaAbzufragende Site.
source_idsstring[]JaLog-Quellen-IDs, die durchsucht werden sollen. Mindestens eine ist erforderlich.
querystringJaAbfragestring, der Log-Zeilen filtert. Siehe Abfragesprache.
use_expressionsbooleanNeinWenn true, wird query mit der ausdrucksbasierten Abfragesprache geparst.
fromstring (ISO 8601)NeinStart des Zeitbereichs. Standardwert ist die untere Grenze der Aufbewahrung.
tostring (ISO 8601)NeinEnde des Zeitbereichs. Standardwert ist die aktuelle Zeit.
paginationobjectJaPaginierungs-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:
FeldTypBeschreibung
idstringBezeichner der Log-Zeile.
timestampstring (ISO 8601)Zeitpunkt, zu dem die Log-Zeile aufgezeichnet wurde.
source_idstringLog-Quelle, zu der die Zeile gehört.
severitystringSchweregrad, etwa info oder error.
messagestringDer Log-Nachrichtentext.
hostnamestringHost, der die Zeile erzeugt hat.
groupstringLog-Gruppe.
jsonstringDer rohe strukturierte (JSON-)Body der Log-Zeile, sofern verfügbar.
attributesobjectVeraltete 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

OperatorNameVerhalten
=GleichExakte Übereinstimmung.
!=UngleichExakte Nicht-Übereinstimmung.
:EnthältTeilstring-Übereinstimmung.
!:Enthält nichtTeilstring-Nicht-Übereinstimmung.
>Größer alsNumerischer Vergleich.
>=Größer oder gleichNumerischer Vergleich.
<Kleiner alsNumerischer Vergleich.
<=Kleiner oder gleichNumerischer 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]
Eine Abfrage, die noch die alte Syntax verwendet, gibt einen 422 mit dem Fehler-Slug legacy_log_query_syntax zurück.