Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Metriken von Hand lesen

Ziel: Du liest /metrics von 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 /metrics als 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 curl und grep. 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: # HELP mit einer Beschreibung und # TYPE mit 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. /healthz ist die Readiness-Probe von Kubernetes, /metrics warst 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_goroutines zählt die laufenden Goroutinen, process_resident_memory_bytes den belegten Speicher – hier rund 20 MB.
  • notes_db_up setzt notes-api bei jedem Healthcheck auf 1 oder 0. Daraus wird an Tag 4 ein Alarm.
  • notes_build_info hat 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.
  • _sum ist die Summe aller Dauern in Sekunden. _sum / _count ergibt 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-api

Erwartet (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-api

Erwartet (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-api

Erwartet:

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_total

Erwartet (die Zahlen weichen ab):

notes_created_total 30
notes_created_total 35
  • port-forward leitet 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 %2

Fortschritt speichern? Kostenlos registrieren

Drill 7: Woher die Zahlen kommen

grep -n "Name:" ~/obs-lab/code/notes-api/metrics.go

Erwartet:

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

Erwartet:

# 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), _total für Counter, ein Präfix pro Anwendung. Die Regeln stehen unter prometheus.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: /metrics spricht auch das standardisierte Format OpenMetrics, wenn der Abrufer es verlangt. Prometheus tut das und bekommt so die Exemplars aus Tag 11.