PromQL ist die Abfragesprache, auf der jeder lesende Teil von Prometheus aufbaut: Dashboards, Alerting-Regeln, Ad-hoc-Debugging. Diese Anleitung baut Schritt für Schritt eine echte Abfrage auf: Gegeben ein Anfragen-Counter, aufgeteilt nach Pfad, Methode und Status, finde jeden Pfad, dessen Fehlerrate über 5 % liegt.

Zeitreihen auswählen

Der einfachste PromQL-Ausdruck ist nur ein Metrikname, der den aktuellen Wert jeder Zeitreihe mit diesem Namen zurückgibt:

http_requests_total

Füge Label-Matcher in geschweiften Klammern hinzu, um das auf eine bestimmte Teilmenge einzugrenzen:

http_requests_total{status="500"}

Das gibt jede Serie namens http_requests_total zurück, deren Label status genau "500" ist, unabhängig von Pfad oder Methode. Matcher können auch Regex-Matching (status=~"5.." für jeden 5xx-Status) und Negation (status!="200") unter anderen Operatoren.

Von einem Counter zu einer Rate

http_requests_total ist ein Counter: Er steigt nur, sein roher Wert (eine große, ständig wachsende Zahl seit dem Prozessstart) ist also nicht das, was du tatsächlich ansehen willst. Du willst wissen, wie schnell er steigt, und genau das berechnet die Funktion rate(): die durchschnittliche Zuwachsrate pro Sekunde über ein gegebenes Zeitfenster.

rate(http_requests_total{status="500"}[5m])

Das gibt für jede passende Serie die durchschnittliche Rate von 500-Fehlern pro Sekunde über die letzten 5 Minuten zurück. Eine verwandte Funktion, irate(), berechnet eine momentane Rate, die nur die letzten zwei Datenpunkte im Bereich nutzt, statt über das gesamte Fenster zu mitteln. irate() reagiert schneller auf plötzliche Spitzen, ist aber auch verrauschter und empfindlicher gegenüber einem einzelnen ungewöhnlichen Scrape; rate() ist der empfohlene Standard für Dashboards und besonders für Alerting, wo meist ein glatteres, weniger spitzenanfälliges Signal gewünscht ist. Greife speziell zu irate(), wenn du einen schnell veränderlichen Counter auf kurzer Zeitskala betrachtest und momentane Änderungen statt eines geglätteten Trends sehen willst.

Labels wegaggregieren, die dich nicht interessieren

rate() gibt weiterhin ein Ergebnis pro ursprünglicher Zeitreihe zurück, eine Linie pro eindeutiger Kombination aus Pfad, Methode und Status. Um eine einzelne Zahl pro Pfad zu bekommen, summiert über die vorhandenen Methoden und Status, nutze einen Aggregationsoperator:

sum by (path) (rate(http_requests_total{status="500"}[5m]))

sum by (path) (...) summiert die Raten, gruppiert nach dem Label path und verwirft jedes andere Label im Ergebnis. Das ist die allgemeine Form der PromQL-Aggregation: Wähle einen Operator (sum, avg, max, min, count und andere) und eine by (...)-Klausel, die benennt, welche Labels ins Ergebnis überleben.

Abfragen mit binären Operatoren kombinieren

Um eine Fehlerrate als Prozentsatz zu berechnen, brauchst du zwei aggregierte Abfragen, fehlerhafte Anfragen und Gesamtanfragen, die gegeneinander dividiert werden:

sum by (path) (rate(http_requests_total{status="500"}[5m]))
/
sum by (path) (rate(http_requests_total[5m]))
* 100

PromQL gleicht die beiden Seiten einer binären Operation anhand ihrer verbleibenden Labels ab, hier path, und berechnet die Division für jedes passende Paar, statt dass du sie von Hand ausrichten musst. Die Multiplikation mit 100 verwandelt das resultierende Verhältnis in einen Prozentsatz.

Das Ergebnis selbst filtern

Umschließe den gesamten Ausdruck, um nur die Ergebnisse zu behalten, die tatsächlich eine Schwelle überschreiten:

(
  sum by (path) (rate(http_requests_total{status="500"}[5m]))
  /
  sum by (path) (rate(http_requests_total[5m]))
  * 100
) > 5

Das gibt nur die Pfade zurück, deren berechneter Fehlerprozentsatz aktuell über 5 liegt, genau die Form von Abfrage, die du in eine Alerting-Regel packen würdest, um jemanden zu alarmieren, wenn sie wahr ist.

Eine Abfrage in einen Alert verwandeln

Eine Alerting-Regel ist ein PromQL-Ausdruck plus Metadaten, die beschreiben, was zu tun ist, wenn er etwas auswertet:

groups:
  - name: example-alerts
    rules:
      - alert: HighErrorRatePerPath
        expr: |
          (
            sum by (path) (rate(http_requests_total{status="500"}[5m]))
            /
            sum by (path) (rate(http_requests_total[5m]))
            * 100
          ) > 5
        for: 10m
        labels:
          severity: page
        annotations:
          summary: "Error rate above 5% on {{ $labels.path }}"

for: 10m verlangt, dass die Bedingung 10 Minuten lang wahr bleibt, bevor der Alert tatsächlich feuert, was vermeidet, bei einem kurzen, sich selbst auflösenden Aussetzer zu alarmieren. Prometheus wertet solche Regeln fortlaufend aus und übergibt alles, was gerade feuert, an den Alertmanager, was dasselbe PromQL ist, das du sonst direkt in ein Grafana-Panel setzen würdest, nur mit einem Namen, einer Dauer und Routing-Metadaten umhüllt.

Wie es weitergeht

Das deckt Instant Vectors, Ratenberechnungen, Aggregation und binäre Operatoren ab, genug, um den Großteil der Abfragen zu lesen und zu schreiben, denen du in bestehenden Dashboards und Alerts begegnest. PromQL hat darüber hinaus mehr (Range-Vector-Funktionen jenseits von rate, Subqueries, weitere Aggregationsoperatoren), gut dokumentiert in Prometheus’ eigener Query-Referenz, die du bei deinen ersten paar echten Abfragen offen halten solltest.