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.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.
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.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.
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.
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 einpagination-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:ASCoderDESC. Zeilen werden nach ihreridsortiert.cursor:{ "id": null }für die erste Seite.
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.
400-Antwort, deren Feld error das Problem benennt:
per_pageakzeptiert Werte von 1 bis 1.000. Andere Werte liefernpagination_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_exceededstatt 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 ingroup_byerscheinen. Der Metrik-namedarf keinen Platzhalter enthalten. Andernfalls liefert die Abfragepagination_requires_deterministic_grouping. - Die Ereignismetriken
event_durationundevent_metricsowie die Incident-Fehlermetrikincident_error_countkönnen noch nicht paginiert werden. Sie liefernpagination_unsupported_for_selector. Fragen Sie sie in einer separaten Anfrage ohnepaginationab.
Metriknamen auflisten
Gibt jeden für eine Site verfügbaren Metriknamen zurück.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.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
Dieuptime_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
phaseden 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,nameoderid, nicht nachphase.
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 Metriklog_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
fieldaufGAUGE. Deraggregation-Tag bestimmt den Wert; dieaggregation-Eigenschaft des Selectors wird ignoriert. - Geben Sie sowohl
source_idals auchqueryan. 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
severitygeben einen400zurück.
- Timeseries: eine Serie pro
group_by-Kombination, mit den Feldwerten alstagsder Serie. - Liste: eine Zeile pro Gruppe, über den gesamten Zeitbereich. Gruppieren
Sie mit dem
group_byder Anfrage, etwa[{"Tag": "severity"}]. Eingroup_by-Tag im Selector gibt einen400zurück. Selectors, die sich eine Gruppe teilen, werden zu einer Zeile zusammengeführt.
signup-Zeilen und bildet den Durchschnitt ihrer
duration, pro Schweregrad:
- 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
limitjeden Selector separat. Einer zusammengeführten Zeile können dann die Werte einiger Selectors fehlen.
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 vonqueue- 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/timeseriesverarbeitet bis zu 100 Serien./api/v2/metrics/listverarbeitet 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.
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
Dasfield 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
Dieaggregation 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.