Tag 1: Metriken von Hand lesen
Ziel: Du liest
/metricsvon notes-api ohne Werkzeug, erkennst Counter, Gauge und Histogramm und weißt, warum jeder Pod eigene Zahlen hat. · Dauer: ca. 45 min · Voraussetzung: Tag 0
Briefing
- Eine Metrik ist eine Zahl mit Namen und
Labels, zum Beispiel
notes_http_requests_total{method="GET",path="/notes",code="200"} 188. Jede Kombination aus Name und Labels ist eine eigene Zeitreihe. - notes-api zeigt seine Metriken unter
/metricsals Text. Prometheus holt diese Seite ab Tag 2 alle paar Sekunden ab und merkt sich jeden Wert mit Zeitstempel. Dieses Abholen heißt Scrape. - Drei Typen reichen für fast alles: Counter zählen nur nach oben, Gauges gehen hoch und runter, Histogramme sortieren Messwerte in Eimer (Buckets).
- Heute arbeitest du nur mit
curlundgrep. So siehst du genau das, was später Prometheus sieht.
curl ──► :30080/metrics ──► Service notes-api ──► Pod A oder Pod B
curl ──► :9081 (port-forward) ──────────────────► Pod A
Drill 1: Die Seite /metrics
curl -s localhost:30080/metrics | grep "^# TYPE notes_"Erwartet:
# TYPE notes_build_info gauge
# TYPE notes_created_total counter
# TYPE notes_db_up gauge
# TYPE notes_http_request_duration_seconds histogram
# TYPE notes_http_requests_total counter
- Vor jeder Metrik stehen zwei Kommentarzeilen:
# HELPmit einer Beschreibung und# TYPEmit dem Typ. Prometheus liest beide mit. - Das Präfix
notes_zeigt, woher die Metrik stammt. Die Endung nennt die Einheit (_seconds) oder sagt, dass gezählt wird (_total).
Daneben liefert die Bibliothek eigene Metriken über Go und den Prozess:
curl -s localhost:30080/metrics | grep -c "^[a-z]"Erwartet (ungefähr):
113
grep -c zählt die Zeilen, die mit einem Kleinbuchstaben
beginnen – also alle Messwerte, keine Kommentare. Rund die Hälfte
beginnt mit go_ oder process_.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Counter
curl -s localhost:30080/metrics | grep "^notes_http_requests_total"Erwartet (die Zahlen weichen ab):
notes_http_requests_total{code="200",method="GET",path="/healthz"} 14
notes_http_requests_total{code="200",method="GET",path="/metrics"} 2
notes_http_requests_total{code="200",method="GET",path="/notes"} 292
notes_http_requests_total{code="201",method="POST",path="/notes"} 70
Wiederhole den Befehl nach ein paar Sekunden. Die Zahlen für
/notes sind gewachsen.
- Ein Counter zählt nur nach oben. Startet der Pod neu, beginnt er wieder bei 0.
- Der absolute Wert sagt wenig: 292 Anfragen seit wann? Interessant
ist, wie schnell der Counter wächst. Das rechnet Prometheus an Tag 3 mit
rate()aus. - Die Labels teilen den Counter auf: Jede Kombination aus Methode,
Pfad und Status bekommt eine eigene Zeile.
/healthzist die Readiness-Probe von Kubernetes,/metricswarst du selbst in Drill 1.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Gauges
curl -s localhost:30080/metrics \
| grep "^\(notes_db_up\|notes_build_info\|go_goroutines\|process_resident\)"Erwartet:
go_goroutines 11
notes_build_info{store="postgres",version="0.8.0"} 1
notes_db_up 1
process_resident_memory_bytes 1.968128e+07
- Ein Gauge ist ein Momentwert: Er geht hoch und
runter.
go_goroutineszählt die laufenden Goroutinen,process_resident_memory_bytesden belegten Speicher – hier rund 20 MB. notes_db_upsetzt notes-api bei jedem Healthcheck auf 1 oder 0. Daraus wird an Tag 4 ein Alarm.notes_build_infohat immer den Wert 1. Die Information steckt in den Labels: Welche Version läuft, mit welchem Speicher? Dieses Muster heißt Info-Metrik.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Histogramm
curl -s localhost:30080/metrics | grep 'method="GET",path="/notes"'Erwartet (gekürzt, die Zahlen weichen ab):
..._bucket{method="GET",path="/notes",le="0.005"} 256
..._bucket{method="GET",path="/notes",le="0.01"} 268
..._bucket{method="GET",path="/notes",le="0.025"} 272
..._bucket{method="GET",path="/notes",le="0.05"} 273
..._bucket{method="GET",path="/notes",le="0.1"} 274
...
..._bucket{method="GET",path="/notes",le="+Inf"} 274
..._sum{method="GET",path="/notes"} 0.8796131480000006
..._count{method="GET",path="/notes"} 274
notes_http_requests_total{code="200",method="GET",path="/notes"} 274
... steht für
notes_http_request_duration_seconds.
- Jede Anfrage landet in allen Buckets, deren Grenze
le(„less or equal“) sie nicht überschreitet. 256 Anfragen dauerten höchstens 5 ms, 268 höchstens 10 ms. Die Buckets sind kumulativ. le="+Inf"enthält alles und ist darum gleich_count._sumist die Summe aller Dauern in Sekunden._sum / _countergibt den Durchschnitt: 0,88 s / 274 ≈ 3 ms.- Die Grenzen legt der Code fest, von 5 ms bis 2,5 s. Ein Histogramm kann nur so genau sein wie seine Buckets.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Eine Störung messen
notes-api kann sich absichtlich verlangsamen. Setze eine Verzögerung von 300 ms:
kubectl -n app set env deploy/notes-api NOTES_DELAY=300ms
kubectl -n app rollout status deploy/notes-apiErwartet (letzte Zeile):
deployment "notes-api" successfully rolled out
set env ändert die Umgebung im Deployment. Kubernetes
ersetzt daraufhin beide Pods, die Zähler beginnen bei 0. Warte eine
halbe Minute, dann:
curl -s localhost:30080/metrics | grep 'bucket{method="GET",path="/notes"'Erwartet (die Zahlen weichen ab):
..._bucket{method="GET",path="/notes",le="0.005"} 0
..._bucket{method="GET",path="/notes",le="0.01"} 0
..._bucket{method="GET",path="/notes",le="0.025"} 0
..._bucket{method="GET",path="/notes",le="0.05"} 0
..._bucket{method="GET",path="/notes",le="0.1"} 0
..._bucket{method="GET",path="/notes",le="0.25"} 0
..._bucket{method="GET",path="/notes",le="0.5"} 47
..._bucket{method="GET",path="/notes",le="1"} 47
..._bucket{method="GET",path="/notes",le="2.5"} 47
..._bucket{method="GET",path="/notes",le="+Inf"} 47
- Alle Anfragen liegen zwischen 250 und 500 ms. Bis zur Grenze 0,25 steht überall 0.
- Genauer als „zwischen 0,25 und 0,5 s“ weiß es das Histogramm nicht. Das reicht für Alarme und Dashboards.
Die Verzögerung wieder entfernen – das Minus hinter dem Namen löscht die Variable:
kubectl -n app set env deploy/notes-api NOTES_DELAY-
kubectl -n app rollout status deploy/notes-apiErwartet (letzte Zeile):
deployment "notes-api" successfully rolled out
Fortschritt speichern? Kostenlos registrieren
Drill 6: Jeder Pod zählt für sich
Über den Service landet jede Anfrage bei irgendeinem Pod – auch die
an /metrics. Mit port-forward sprichst du
einen bestimmten Pod direkt an:
kubectl -n app get pods -l app.kubernetes.io/name=notes-apiErwartet:
NAME READY STATUS RESTARTS AGE
notes-api-57f4f47769-s8cmj 1/1 Running 0 67s
notes-api-57f4f47769-vd8wp 1/1 Running 0 63s
Steht noch ein dritter Pod mit Completed oder
Terminating dabei, ist das ein alter aus Drill 5. Warte,
bis er verschwunden ist.
Setze deine Pod-Namen ein:
kubectl -n app port-forward notes-api-57f4f47769-s8cmj 9081:8080 >/dev/null &
kubectl -n app port-forward notes-api-57f4f47769-vd8wp 9082:8080 >/dev/null &
curl -s localhost:9081/metrics | grep ^notes_created_total
curl -s localhost:9082/metrics | grep ^notes_created_totalErwartet (die Zahlen weichen ab):
notes_created_total 30
notes_created_total 35
port-forwardleitet einen Port der VM zu einem Pod weiter. Das&schickt den Befehl in den Hintergrund, die Shell bleibt frei.- Jeder Pod zählt nur, was er selbst bearbeitet hat. Die Wahrheit ist die Summe beider Zahlen.
- Darum fragt Prometheus nie den Service, sondern jeden Pod einzeln. Woher es die Pods kennt, siehst du an Tag 2.
Die Weiterleitungen beenden:
kill %1 %2Fortschritt speichern? Kostenlos registrieren
Drill 7: Woher die Zahlen kommen
grep -n "Name:" ~/obs-lab/code/notes-api/metrics.goErwartet:
30: Name: "notes_http_requests_total",
34: Name: "notes_http_request_duration_seconds",
39: Name: "notes_created_total",
43: Name: "notes_db_up",
48: Name: "notes_build_info",
- Die Metriken entstehen mit
client_golang, der offiziellen Go-Bibliothek von Prometheus. Für Java, Python, .NET und Node gibt es Gegenstücke. - Eine Middleware am Ende der Datei legt sich um jeden Handler, zählt jede Anfrage und misst ihre Dauer. Die Handler selbst wissen nichts von Metriken.
Rufe einen Pfad auf, den es nicht gibt:
curl -s localhost:30080/gibtsnicht
curl -s localhost:30080/metrics | grep 'path="other"'Erwartet (die zweite Zeile kann leer bleiben – dann antwortete der andere Pod):
404 page not found
notes_http_requests_total{code="404",method="GET",path="other"} 1
Unbekannte Pfade landen unter other. Würde notes-api
jeden Pfad als Label speichern, könnte jeder Besucher mit erfundenen
URLs beliebig viele Zeitreihen erzeugen. Dieses Problem heißt
Kardinalität und kommt an Tag 14 wieder.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
curl -s localhost:30080/metrics | grep -c 'bucket{method="GET",path="/notes"'Erwartet:
10
Neun Grenzen aus dem Code plus +Inf.
kubectl -n app set env deploy/notes-api --listErwartet:
# Deployment notes-api, container notes-api
# NOTES_API_KEY from secret notes, key api-key
# NOTES_DB_URL from secret notes, key db-url
# Deployment notes-api, container migrate
# NOTES_DB_URL from secret notes, key db-url
--list zeigt die Umgebung, ohne etwas zu ändern.
NOTES_DELAY ist wieder weg, keine Störung mehr aktiv.
Challenge
Sorge dafür, dass in /metrics eine Zeitreihe mit
code="401" auftaucht.
Hinweis: Welche Anfrage lehnt notes-api mit 401 ab? Und denk an Drill 6.
Lösung
POST /notes ohne API-Key:
curl -s -d '{"text":"x"}' localhost:30080/notes
curl -s localhost:30080/metrics | grep 'code="401"'Erwartet:
{"error":"invalid api key"}
notes_http_requests_total{code="401",method="POST",path="/notes"} 1
Bleibt die zweite Zeile leer, kam die Anfrage an den einen Pod und
die Abfrage von /metrics an den anderen. Wiederhole beide
Befehle ein paarmal.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Namen nach Konvention: Basiseinheiten (Sekunden,
Bytes),
_totalfür Counter, ein Präfix pro Anwendung. Die Regeln stehen unterprometheus.io/docs/practices/naming. Wer sie einhält, bekommt fertige Dashboards und Alarme von anderen ohne Umbenennen. - Keine IDs als Label: Benutzer-IDs, Notiz-IDs oder volle URLs gehören nie in Labels. Jeder neue Wert ist eine neue Zeitreihe – und Speicher in Prometheus.
- OpenMetrics:
/metricsspricht auch das standardisierte Format OpenMetrics, wenn der Abrufer es verlangt. Prometheus tut das und bekommt so die Exemplars aus Tag 11.