Jeder Teil von Prometheus, Scraping, Speicher, PromQL, Alerting, arbeitet auf derselben zugrunde liegenden Struktur: einer Zeitreihe, identifiziert durch einen Namen und eine Menge von Labels, bestehend aus einem Strom von Werten mit Zeitstempel. Diese Anleitung behandelt diese Struktur und das Klartextformat, das Targets nutzen, um sie bereitzustellen.

Eine Zeitreihe ist ein Name, eine Menge von Labels und ein Strom von Samples

Ein Metrikname beschreibt, was gemessen wird: http_requests_total, process_open_fds, node_memory_available_bytes. Für sich genommen ist ein Metrikname noch keine einzelne Zeitreihe, sondern eine Familie, die Labels in einzelne Serien unterteilen. Labels sind Schlüssel-Wert-Paare, die an eine Metrik gehängt werden: method="GET", status="500", path="/api/users". Die Kombination aus einem Metriknamen plus einer bestimmten Menge von Label-Werten identifiziert genau eine Zeitreihe.

http_requests_total{method="GET", status="200", path="/api/users"}
http_requests_total{method="GET", status="500", path="/api/users"}
http_requests_total{method="POST", status="200", path="/api/orders"}

Das sind drei verschiedene Zeitreihen, die einen Metriknamen teilen. Prometheus hängt automatisch auch eigene Labels an, die angeben, von welchem Target und Job eine Serie stammt, zusätzlich zu allem, was die Anwendung selbst bereitzustellen gewählt hat.

Ein Sample ist ein Punkt in einer Serie: ein 64-Bit-Millisekunden-Zeitstempel (meist der Moment des Scrapes), gepaart mit einem 64-Bit-Gleitkommawert. Eine Serie ist der fortlaufende Strom dieser Samples, der sich mit einem pro Scrape über die Zeit ansammelt.

Die vier Metriktypen

Prometheus’ Client-Bibliotheken stellen vier Arten von Metriken bereit, die jeweils etwas anderes bedeuten, wenn du sie abfragst:

• Counter: ein Wert, der nur ansteigt (oder beim Neustart auf null zurückgesetzt wird), wie eine laufende Summe bearbeiteter Anfragen. Den rohen Wert eines Counters liest du fast nie; du berechnest eine Änderungsrate darüber, in der PromQL-Anleitung behandelt.
• Gauge: ein Wert, der steigen oder fallen kann, wie aktuelle Speichernutzung oder eine Zahl laufender Anfragen. Wird direkt gelesen, anders als ein Counter.
• Histogram: ordnet Beobachtungen (Anfragedauern, Antwortgrößen) in konfigurierbare Buckets ein und stellt daneben eine Anzahl und eine Summe bereit, was nachträgliche Quantilberechnungen (wie „95. Perzentil der Latenz“) aus gespeicherten Bucket-Daten ermöglicht.
• Summary: ähnlich einem Histogramm, berechnet Quantile aber clientseitig zum Beobachtungszeitpunkt statt aus Buckets. Günstiger abzufragen, aber Summary-Quantile lassen sich nicht über Instanzen hinweg aggregieren, wie es Histogramm-Buckets können, weshalb Histogramme die häufigere Wahl für alles sind, was du über eine Flotte aggregierst.

Ein natives Histogramm, das Histogrammdaten in voller Auflösung effizienter speichert als die ältere Bucket-Form, ist seit einer Weile in aktiver Entwicklung; prüfe die aktuelle Prometheus-Dokumentation auf seine derzeitige Reife, bevor du dich darauf verlässt, da sich verschoben hat, wie offiziell unterstützt es genau ist, über die letzten Releases hinweg.

Das Exposition-Format

Damit Prometheus ein Target abfragen kann, stellt dieses Target seine aktuellen Werte per HTTP als Klartext in einem bestimmten, bewusst einfachen Layout bereit:

# HELP http_requests_total Total number of HTTP requests handled.
# TYPE http_requests_total counter
http_requests_total{method="GET", status="200"} 8420
http_requests_total{method="GET", status="500"} 12

# HELP process_open_fds Number of open file descriptors.
# TYPE process_open_fds gauge
process_open_fds 27

# HELP- und # TYPE-Zeilen sind Kommentare, die Dokumentation und den Typ der Metrik liefern; jede andere Nicht-Kommentar-Zeile ist der aktuelle Wert einer Serie, als Metrikname, ihre Labels in geschweiften Klammern und der Wert selbst. Weil das immer nur ein Schnappschuss ist, eine Zeile pro Serie, die ihren Wert genau jetzt zeigt, gibt es in einer Scrape-Antwort keine Historie; Historie existiert erst, wenn Prometheus dieselbe Serie wiederholt über die Zeit abgefragt und jedes Ergebnis gespeichert hat.

Die Einfachheit des Formats ist beabsichtigt: Es soll trivial zu erzeugen sein, auch ohne Client-Bibliothek, und das macht es realistisch, Prometheus-Metriken aus fast allem herauszubekommen, nicht nur aus Software mit offizieller Bibliotheksunterstützung.

Selbst ansehen

Weil Scraping nur ein HTTP-GET ist, kannst du die aktuellen Metriken jedes Targets direkt im Browser oder mit curl ansehen, ohne Prometheus-Server:

curl http://localhost:9100/metrics   # zum Beispiel eine node_exporter-Instanz

Diese Ausgabe ist genau das, was Prometheus selbst bei jedem Scrape erhält, was sie zu einem wirklich nützlichen ersten Schritt bei der Fehlersuche macht: Wenn ein Target in Prometheus nicht richtig erscheint, sagt dir ein Blick auf seine rohe /metrics-Ausgabe direkt, ob das Problem das Target ist oder etwas in Prometheus’ eigener Scrape-Konfiguration.

Woher Labels kommen und warum sie später wichtig sind

Die eigenen Labels eines Targets (welcher Endpunkt, welche Methode, welcher Statuscode) stammen daher, wie sich die Anwendung oder der Exporter selbst instrumentiert hat. Prometheus fügt eigene hinzu, die den Job und die konkrete Instanz identifizieren, von der eine Serie abgefragt wurde. Zusammen sind diese Labels das, worauf PromQLs Aggregation und Filterung arbeiten. Sie lassen dich nach „Fehlerrate über jede Instanz“ oder „Anfragerate nur für diesen einen Pfad“ gegen dieselben zugrunde liegenden Daten fragen, was genau das ist, was die nächste Anleitung dieser Reihe behandelt.