Zum Hauptinhalt springen
Lesen Sie Metrikdaten mit der Public API (V2). Holen Sie eine Zeitreihe für Graphen, eine aggregierte Liste für Tabellen oder ermitteln Sie, welche Metriken und Tags eine Site bietet. Alle Endpunkte authentifizieren sich mit Ihrem persönlichen API-Token und sind auf eine einzelne site_id begrenzt. Diese Seite erklärt, wie Sie Metrik-Abfragen aufbauen. Alle Felder jeder Anfrage und Antwort finden Sie in der Referenz der Metrik-Endpunkte.

Migration von GraphQL-Metriken

Das Lesen von Metriken über die GraphQL-API ist veraltet. Wenn Ihre Integration Metrikdaten über GraphQL liest, verwenden Sie diesen Vergleich, um sie auf den REST-API-(V2)-Timeseries-Endpunkt umzustellen.

Eine Zeitreihe abfragen

Dieser Endpunkt gibt eine oder mehrere Serien von Datenpunkten über einen Zeitbereich zurück. Verwenden Sie ihn zum Zeichnen von Graphen.
Die Anfrage nimmt eine site_id, einen from- und to-Zeitbereich und ein select-Array entgegen. Lassen Sie resolution weg, wählt AppSignal eine passend zum Zeitbereich. Siehe Auflösungen. Jeder select-Eintrag fragt ein Metrikfeld ab. Geben Sie einen Metrik-name, ein tags-Objekt und ein field an (siehe Felder). Tag-Werte können * als Platzhalter verwenden. Sie können außerdem eine aggregation angeben (siehe Aggregationen) sowie einen fill-Wert. Die fill-Werte sind ZERO (Standard), PREVIOUS und NONE. Bestehende Integrationen können auch das optionale Feld draw_null_as_zero verwenden. true füllt fehlende Punkte mit null auf, wie ZERO. false übernimmt den vorherigen Wert, wie PREVIOUS. Wenn Sie beide Felder senden, hat fill Vorrang. Verwenden Sie für field und aggregation Großbuchstaben. Der Timeseries-Endpunkt unterstützt kein group_by. Die Referenz führt ein limit-Feld auf, aber der Timeseries-Endpunkt wendet es nicht an. Die Anzahl der Serien wird stattdessen durch die Verarbeitungsgrenzen begrenzt. Diese Anfrage ruft die mittlere trace_duration des Namespace web ab. Ihr draw_null_as_zero: false übernimmt bei fehlenden Punkten den letzten Wert.
Die Antwort hat ein series-Array mit einer Serie pro Tag- und Feld-Kombination, die Daten zurückgegeben hat. Anders als die GraphQL-Metriken-API benötigt dieser Endpunkt keine separate Anfrage für Metrik-Schlüssel. Verwenden Sie das series-Array, um zu sehen, welche Tag- und Feld-Kombinationen Daten zurückgegeben haben. Wenn eine Abfrage die Verarbeitungsgrenzen erreichen könnte, verwenden Sie series.length nicht als Gesamtzahl der übereinstimmenden Metrik-Schlüssel.

Eine Liste abfragen

Dieser Endpunkt gibt aggregierte Metrikwerte gruppiert in Zeilen zurück. Verwenden Sie ihn, um Tabellen zu erstellen.
Die Anfrage nimmt dieselbe site_id, from, to und optionale resolution wie eine Timeseries-Abfrage entgegen, plus ein group_by-Array. Siehe Auflösungen. Um die Anzahl der Zeilen zu begrenzen, fügen Sie limit hinzu oder paginieren Sie die Liste. Ein Listen-Selector ist wie ein Timeseries-Selector, mit einer zusätzlichen id. Die id benennt den Wert des Selectors im data-Objekt jeder Zeile. Jeder group_by-Eintrag ist einer der folgenden, und beide sind case-sensitiv:
  • Der String "Name", um nach Metrikname zu gruppieren.
  • Ein Objekt wie {"Tag": "hostname"}, um nach dem Wert eines Tags zu gruppieren.
Verwenden Sie für field und aggregation Großbuchstaben. Wenn ein Selector in tags * für einen Tag verwendet, fügen Sie denselben Tag als {"Tag": "tag_name"} zu group_by hinzu, sonst schlägt die Anfrage fehl.
Die Antwort hat ein rows-Array. Jede Zeile hat ein group-Objekt mit den Tag-Werten, die sie definieren. Ihr data-Objekt enthält die aggregierten Werte, indiziert nach Selector-id, zum Beispiel { "mean": 42.5 }.

Eine Liste paginieren

Fügen Sie dem Request-Body ein pagination-Objekt hinzu, um die Liste seitenweise zu lesen. Es benötigt alle drei dieser Felder:
  • per_page: wie viele Zeilen pro Seite zurückgegeben werden.
  • order: ASC oder DESC. Zeilen werden nach ihrer id sortiert.
  • cursor: { "id": null } für die erste Seite.
Wenn eine Anfrage sowohl pagination als auch limit enthält, hat pagination Vorrang. Um die nächste Seite zu erhalten, senden Sie dieselbe Anfrage mit cursor.id auf die id der letzten Zeile gesetzt. Wiederholen Sie dies, bis eine Seite mit weniger Zeilen als per_page zurückkommt. Diese Seite ist die letzte. Eine paginierte Antwort hat dieselbe Form wie jede andere Listen-Antwort.
Die Paginierung hat Grenzwerte. Eine Anfrage außerhalb dieser Grenzwerte liefert eine 400-Antwort, deren Feld error das Problem benennt:
  • per_page akzeptiert Werte von 1 bis 1.000. Andere Werte liefern pagination_invalid_per_page.
  • Eine paginierte Abfrage liest über alle ihre Seiten hinweg bis zu 100.000 Metrik-Schlüssel oder Zeilen. Wird dieser Grenzwert überschritten, liefert sie pagination_key_limit_exceeded statt eines Teilergebnisses. Grenzen Sie die Tag-Filter oder den Zeitbereich ein und senden Sie die Anfrage erneut.
  • Bei benutzerdefinierten Metriken muss jeder Tag, der einen *-Platzhalter verwendet, auch in group_by erscheinen. Der Metrik-name darf keinen Platzhalter enthalten. Andernfalls liefert die Abfrage pagination_requires_deterministic_grouping.
  • Die Ereignismetriken event_duration und event_metric sowie die Incident-Fehlermetrik incident_error_count können noch nicht paginiert werden. Sie liefern pagination_unsupported_for_selector. Fragen Sie sie in einer separaten Anfrage ohne pagination ab.

Metriknamen auflisten

Gibt jeden für eine Site verfügbaren Metriknamen zurück.
Gibt ein Array von Strings zurück. Verwenden Sie einen davon als name in den select-Einträgen einer Abfrage. Wie Sie ihn abfragen, erfahren Sie, wenn Sie seinen Typ und seine Tags abrufen. Die vollständige Antwort finden Sie in der Referenz Metriknamen auflisten. Um die Liste einzugrenzen, fügen Sie einen filter-Query-Parameter hinzu, etwa ?filter=queue. Er gibt nur Namen zurück, die diesen Begriff enthalten, ohne Berücksichtigung der Groß-/Kleinschreibung, mit bis zu 200 Zeichen. Benutzerdefinierte Metriken erscheinen nur, wenn sie in den letzten 24 Stunden gemeldet wurden. Die Liste enthält höchstens 1.000 davon, und filter sucht auch über diese 1.000 hinaus.

Typ und Tags einer Metrik abrufen

Gibt den Typ einer Metrik und die Tag-Kombinationen zurück, mit denen sie abgefragt werden kann.
Gibt einen metric_type (GAUGE, COUNTER oder MEASUREMENT) und available_tags zurück, ein Array, dessen Einträge jeweils eine gültige Kombination von Tag-Schlüsseln sind. Der Typ bestimmt, welche Felder Sie auswählen können. Eine GAUGE-Metrik hat das Feld GAUGE, und eine COUNTER-Metrik hat das Feld COUNTER. Eine MEASUREMENT-Metrik hat MEAN, COUNT, MIN, MAX und die Perzentile. Verwenden Sie eine Tag-Kombination als Schlüssel der tags eines Selectors. Die vollständige Antwort finden Sie in der Referenz Typ und Tags einer Metrik abrufen.

Uptime-Monitor-Timings

Die uptime_monitor_timing-Metrik ist ein Gauge, der erfasst, wie lange jede Phase einer Uptime-Prüfung gedauert hat, in Millisekunden. Der Tag phase wählt die Phase aus: dns, connect, tls, ttfb, download oder total. Was jede Phase misst, steht unter Anfrage-Timing. Fragen Sie die Metrik mit region, phase und entweder dem name oder der id des Monitors ab. phase verhält sich in den beiden Abfrage-Endpunkten unterschiedlich:
  • In einer Timeseries-Abfrage akzeptiert phase den Platzhalter * und gibt eine Serie pro Phase zurück.
  • In einer Listenabfrage muss jeder Selector eine Phase benennen. Fügen Sie einen Selector pro gewünschter Phase hinzu, und gruppieren Sie nach region, name oder id, nicht nach phase.
Eine Phase, die die Prüfung nicht gemessen hat, fehlt in der Antwort. Das betrifft tls bei einer reinen HTTP-URL und download ohne Body-Check. Diese Listenanfrage gibt die mittlere Zeit pro Phase und Region für einen Monitor zurück:

Log-Metriken

Die Metrik log_metrics macht aus Log-Zeilen Zahlen. Sie zählt passende Zeilen oder bildet Summe, Durchschnitt, Minimum oder Maximum eines numerischen Felds. AppSignal berechnet sie bei der Abfrage, daher deckt sie auch Logs ab, die Sie bereits gesendet haben. Fragen Sie sie über den Timeseries- oder Listen-Endpunkt ab, und konfigurieren Sie sie über die tags des Selectors: Für jeden Selector:
  • Setzen Sie field auf GAUGE. Der aggregation-Tag bestimmt den Wert; die aggregation-Eigenschaft des Selectors wird ignoriert.
  • Geben Sie sowohl source_id als auch query an. Ohne sie gibt der Selector nichts zurück, und auch keinen Fehler.
  • Benennen Sie Felder in Punktnotation, etwa user.age.
  • Aggregieren Sie nur Felder aus dem JSON Ihres Logs. Eingebaute Felder wie severity geben einen 400 zurück.
Der Zeitbereich ist auf Ihre Log-Aufbewahrung begrenzt. Die Ergebnisse werden so gruppiert:
  • Timeseries: eine Serie pro group_by-Kombination, mit den Feldwerten als tags der Serie.
  • Liste: eine Zeile pro Gruppe, über den gesamten Zeitbereich. Gruppieren Sie mit dem group_by der Anfrage, etwa [{"Tag": "severity"}]. Ein group_by-Tag im Selector gibt einen 400 zurück. Selectors, die sich eine Gruppe teilen, werden zu einer Zeile zusammengeführt.
Diese Anfrage zählt die signup-Zeilen und bildet den Durchschnitt ihrer duration, pro Schweregrad:
Wissenswertes zu Listenergebnissen:
  • Eine Zeile lässt einen Selector weg, dessen Feld in dieser Gruppe keinen numerischen Wert hat.
  • Zeilen ohne das gruppierte Feld werden unter einem leeren String gruppiert.
  • Das aggregierte Feld kann nicht gleichzeitig ein group_by-Feld sein.
  • Ohne Paginierung begrenzt limit jeden Selector separat. Einer zusammengeführten Zeile können dann die Werte einiger Selectors fehlen.
Das Gruppieren nach einem Feld mit vielen Werten, etwa einer User-ID, verlangsamt die Abfrage.

Metrik-Abfragen mit hoher Kardinalität

Eine Metrik-Abfrage hat eine hohe Kardinalität, wenn sie mehr Serien erfasst, als der Endpunkt verarbeiten kann. AppSignal speichert jede eindeutige Tag-Kombination als eigenen Metrik-Schlüssel. Zum Beispiel erzeugt jede Kombination von queue- und worker-Werten einen eigenen Metrik-Schlüssel. Die Grenzwerte in diesem Abschnitt gelten für benutzerdefinierte Metriken und transaction_duration. Sie gelten auch für incident_error_count, wenn eine Abfrage einen Platzhalter für incident_digest oder revision verwendet. Sie gelten nicht für andere Metriken in der aktuellen V2-Implementierung. Jede Kombination aus Metrik-Schlüssel und Feld zählt als eine Serie. Das Anfordern von MEAN und COUNT für einen Metrik-Schlüssel zählt zum Beispiel als zwei Serien. Für betroffene Metriken begrenzt AppSignal, wie viele Serien es verarbeitet, bevor es ihre Daten abruft:
  • /api/v2/metrics/timeseries verarbeitet bis zu 100 Serien.
  • /api/v2/metrics/list verarbeitet bis zu 1.000 Serien pro Seite. Eine paginierte Abfrage kann über alle ihre Seiten hinweg bis zu 100.000 Metrik-Schlüssel lesen. Siehe Eine Liste paginieren.
Diese Grenzwerte schützen die Metrikdatenbank vor Abfragen, die zu lange zur Fertigstellung bräuchten. Sie gelten für die gesamte Antwort, nicht separat für jeden select-Eintrag. Das Feld limit kann sie nicht erhöhen. Dashboard-Diagramme laden ihre Daten von /api/v2/metrics/timeseries, daher gilt die Grenze von 100 Serien auch für Diagramme. Wenn eine Abfrage mehr Serien erfasst, als der Endpunkt verarbeiten kann, gibt AppSignal nur einen Teil der Daten zurück. Die Antwort zeigt nicht an, dass sie unvollständig ist, sodass aggregierte Summen zu niedrig ausfallen können. Das Wiederholen derselben Abfrage liefert dieselbe Teilmenge, das Ergebnis bleibt jedoch unvollständig. Um mehr Serien aus einer Listenabfrage zu lesen, blättern Sie durch sie. Eine paginierte Abfrage, die mehr als 100.000 Metrik-Schlüssel erfasst, liefert pagination_key_limit_exceeded statt eines Teilergebnisses. Die Seite Grenzwerte zeigt, welche benutzerdefinierten Metriken pro Minute die meisten eindeutigen Tag-Kombinationen melden. Wenn sich Tag-Werte über die Zeit ändern, kann eine Abfrage über einen längeren Zeitraum mehr Serien erfassen, als die Seite zeigt. Benutzerdefinierte Metriken funktionieren am besten mit Tags, die eine kleine, feste Menge an Werten haben, wie region, plan oder queue. Wenn eine bestehende Metrik Tags mit hoher Kardinalität hat, können exakte Tag-Filter die Anzahl der übereinstimmenden Serien verringern, aber die Antwort kann nicht bestätigen, dass sie jede Serie enthält. Siehe Metrik-Tags für Hinweise zur Wahl von Tag-Werten.

Referenz

Felder

Das field wählt aus, welche Messung aus einer Metrik abgerufen wird: Welche Felder eine Metrik hat, erfahren Sie, wenn Sie ihren Typ und ihre Tags abrufen. Alle Typen der API finden Sie in der maschinenlesbaren Referenz.

Aggregationen

Die aggregation kombiniert mehrere Werte innerhalb eines Zeitfensters: SUM, AVERAGE, MIN, MAX, FIRST oder LAST. Wenn Sie aggregation weglassen, hängt der Standardwert vom Feld ab:

Auflösungen

resolution akzeptiert MINUTELY, HOURLY oder DAILY. MINUTELY gilt nur, wenn der Zeitbereich 12 Stunden oder kürzer ist und innerhalb der letzten 48 Stunden beginnt. Außerhalb dieses Zeitfensters verwendet AppSignal stattdessen HOURLY und gibt dies im resolution-Feld der Antwort an.