Metriken abfragen - AppSignal Documentation

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.

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.

Was Sie brauchen	GraphQL-Metriken	REST-API (V2)
Endpunkt	`POST https://appsignal.com/graphql?token=YOUR-TOKEN`	`POST https://appsignal.com/api/v2/metrics/timeseries`
Authentifizierung	Persönliches API-Token als URL-Query-Parameter	Persönliches API-Token als Bearer-Header oder als URL-Query-Parameter. Siehe Authentifizierung.
App-Kennung	App-ID an `app(id: $appId)` übergeben	App-ID als `site_id` im Request-Body übergeben.
Tag-Filter	Ein Array von Schlüssel-Wert-Paaren, etwa `[{ "key": "namespace", "value": "web" }]`	Ein Objekt, etwa `{ "namespace": "web" }`
Felder	Ein `fields`-Array bei jeder Metrik-Abfrage	Ein einzelnes großgeschriebenes `field` pro `select`-Eintrag, etwa `"MEAN"` oder `"P90"`. Verwenden Sie auch für `aggregation` Großbuchstaben.
Übereinstimmende Daten	`app.metrics.keys` und `app.metrics.timeseries` getrennt abfragen.	Eine einzelne Timeseries-Anfrage stellen. Das zurückgegebene `series`-Array benennt die Tag- und Feld-Kombinationen, für die Daten zurückkamen. Verarbeitungsgrenzen können diese Liste unvollständig machen.
Paginierung	`metrics.list` und `metrics.keys` akzeptieren `limit` und `offset`.	Kein `offset`. Der Listen-Endpunkt akzeptiert ein `pagination`-Objekt mit einem Zeilen-`id`-Cursor. Siehe Eine Liste paginieren. Der Timeseries-Endpunkt bietet keine Paginierung, und seine Ergebnisse werden durch die Verarbeitungsgrenzen begrenzt.
Fehlende Datenpunkte	Die Metrik-Abfrage legt nicht fest, wie fehlende Punkte aufgefüllt werden.	Verwenden Sie das optionale Feld `fill`. Es akzeptiert `"ZERO"`, `"PREVIOUS"` oder `"NONE"` und ist standardmäßig `"ZERO"`. Das veraltete Feld `draw_null_as_zero` wird ebenfalls unterstützt.

Eine Zeitreihe abfragen

Dieser Endpunkt gibt eine oder mehrere Serien von Datenpunkten über einen Zeitbereich zurück. Verwenden Sie ihn zum Zeichnen von Graphen.

POST /api/v2/metrics/timeseries

Request-Body

Feld	Typ	Erforderlich	Beschreibung
`site_id`	string	Ja	Abzufragende Site.
`from`	string (ISO 8601)	Ja	Start des Zeitbereichs (inklusive).
`to`	string (ISO 8601)	Ja	Ende des Zeitbereichs (inklusive).
`select`	TimeseriesSelector[]	Ja	Welche Metriken, Felder und Tags abgerufen werden.
`resolution`	Resolution	Nein	Intervall zwischen Datenpunkten. Wird bei Weglassen automatisch gewählt. Siehe Auflösungen.
`limit`	number	Nein	Angeforderte maximale Anzahl zurückzugebender Serien. Dieses Feld wird derzeit nicht auf Timeseries-Abfragen angewendet.

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. 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.

{
  "site_id": "YOUR-SITE-ID",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T01:00:00Z",
  "resolution": "MINUTELY",
  "select": [
    {
      "name": "trace_duration",
      "tags": { "namespace": "web" },
      "field": "MEAN",
      "aggregation": "AVERAGE",
      "draw_null_as_zero": false
    }
  ]
}

Antwort

Gibt eine Timeseries mit der abgefragten resolution, from, to und einem series-Array zurück. Jede Serie hat eine id, den Metrik-name, ihre tags, das field, das sie repräsentiert, min und max über den Bereich sowie ein data-Array von Punkten. Jeder Punkt hat einen timestamp und einen numerischen value. 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.

POST /api/v2/metrics/list

Request-Body

Feld	Typ	Erforderlich	Beschreibung
`site_id`	string	Ja	Abzufragende Site.
`from`	string (ISO 8601)	Ja	Start des Zeitbereichs (inklusive).
`to`	string (ISO 8601)	Ja	Ende des Zeitbereichs (inklusive).
`select`	ListSelector[]	Ja	Welche Metriken, Felder und Tags abgerufen werden.
`group_by`	GroupBy[]	Ja	Wie Zeilen gruppiert werden.
`resolution`	Resolution	Nein	Intervall für die Aggregation. Siehe Auflösungen.
`limit`	number	Nein	Maximale Anzahl zurückzugebender Zeilen.
`pagination`	object	Nein	Cursor-basierte Paginierung. Siehe Eine Liste paginieren.

Ein ListSelector ist wie ein Timeseries-Selector mit einer zusätzlichen id, die den Wert des Selectors im data-Objekt jeder Zeile benennt. group_by-Einträge sind Name (nach Metrikname gruppieren) oder Tag (nach Tag-Wert gruppieren). Verwenden Sie für field und aggregation Großbuchstaben. Die case-sensitiven group_by-Werte sind Name und Tag. 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.

{
  "site_id": "YOUR-SITE-ID",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T01:00:00Z",
  "resolution": "HOURLY",
  "select": [
    {
      "id": "mean",
      "name": "trace_duration",
      "tags": { "namespace": "*" },
      "field": "MEAN",
      "aggregation": "AVERAGE"
    }
  ],
  "group_by": [{ "Tag": "namespace" }],
  "limit": 50
}

Antwort

Gibt eine List mit der abgefragten resolution, from, to und einem rows-Array zurück. Jede Zeile hat eine id, ein group-Objekt mit den Tag-Werten, die sie definieren, und ein data-Objekt mit aggregierten Werten, 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:

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.

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.

{
  "site_id": "YOUR-SITE-ID",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T01:00:00Z",
  "resolution": "HOURLY",
  "select": [
    {
      "id": "mean",
      "name": "trace_duration",
      "tags": { "namespace": "*" },
      "field": "MEAN",
      "aggregation": "AVERAGE"
    }
  ],
  "group_by": [{ "Tag": "namespace" }],
  "pagination": {
    "per_page": 100,
    "order": "ASC",
    "cursor": { "id": null }
  }
}

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.

GET /api/v2/metrics/names/{site_id}

Gibt ein Array von Strings zurück.

Typ und Tags einer Metrik abrufen

Gibt den Typ einer Metrik und die Tag-Kombinationen zurück, mit denen sie abgefragt werden kann.

GET /api/v2/metrics/type_and_tags/{site_id}/{metric_name}

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.

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:

{
  "site_id": "YOUR-SITE-ID",
  "from": "2026-10-08T08:00:00Z",
  "to": "2026-10-08T09:00:00Z",
  "resolution": "HOURLY",
  "select": [
    {
      "id": "dns",
      "name": "uptime_monitor_timing",
      "tags": { "id": "YOUR-MONITOR-ID", "region": "*", "phase": "dns" },
      "field": "GAUGE",
      "aggregation": "AVERAGE"
    },
    {
      "id": "ttfb",
      "name": "uptime_monitor_timing",
      "tags": { "id": "YOUR-MONITOR-ID", "region": "*", "phase": "ttfb" },
      "field": "GAUGE",
      "aggregation": "AVERAGE"
    }
  ],
  "group_by": [{ "Tag": "region" }]
}

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:

Wert	Beschreibung
`GAUGE`	Der Wert der Metrik zu einem einzelnen Zeitpunkt, etwa aktuelle CPU- oder Speichernutzung.
`COUNTER`	Aus `COUNTER`-Metriken der kumulierte Wert, der mit der Zeit nur steigt, etwa die Anzahl bedienter Anfragen.
`MEAN`	Der Mittelwert der im Zeitfenster aufgezeichneten Werte, etwa die durchschnittliche Antwortzeit.
`COUNT`	Aus `MEASUREMENT`-Metriken: wie viele Werte im Zeitfenster aufgezeichnet wurden.
`MIN`	Der niedrigste im Zeitfenster aufgezeichnete Wert.
`MAX`	Der höchste im Zeitfenster aufgezeichnete Wert.
`P99`, `P95`, `P90`, `P80`, `P75`, `P70`, `P60`, `P50`, `P40`, `P30`, `P20`, `P10`	Perzentilwerte.

Weitere Typreferenzen finden Sie in der AppSignal V2 API-Dokumentation.

Aggregationen

Die aggregation kombiniert mehrere Werte innerhalb eines Zeitfensters: SUM, AVERAGE, MIN, MAX, FIRST oder LAST.

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.

​Migration von GraphQL-Metriken

​Eine Zeitreihe abfragen

​Request-Body

​Antwort

​Eine Liste abfragen

​Request-Body

​Antwort

​Eine Liste paginieren

​Metriknamen auflisten

​Typ und Tags einer Metrik abrufen

​Uptime-Monitor-Timings

​Metrik-Abfragen mit hoher Kardinalität

​Referenz

​Felder

​Aggregationen

​Auflösungen

Migration von GraphQL-Metriken

Eine Zeitreihe abfragen

Request-Body

Antwort

Eine Liste abfragen

Request-Body

Antwort

Eine Liste paginieren

Metriknamen auflisten

Typ und Tags einer Metrik abrufen

Uptime-Monitor-Timings

Metrik-Abfragen mit hoher Kardinalität

Referenz

Felder

Aggregationen

Auflösungen