Tag 1: Alarme entstehen
Ziel: Prometheus sammelt Metriken von notes-api, wertet drei Alarmregeln aus, und du siehst einen Alarm von inactive über pending bis firing. · Dauer: ca. 50 min · Voraussetzung: Tag 0
Briefing
- Der Alertmanager erzeugt keine Alarme. Das macht Prometheus: Eine Alarmregel ist eine PromQL-Abfrage. Liefert sie Zeitreihen, ist der Alarm aktiv, eine Zeitreihe pro Alarm.
for: 1mheißt: Die Bedingung muss eine Minute lang ununterbrochen gelten. Bis dahin ist der Alarm pending, danach firing. Erst firing-Alarme gehen an den Alertmanager.- Labels an der Regel (
severity,team) entscheiden später, wohin ein Alarm geht. Annotations (summary,runbook_url) sind Text für Menschen. - Wer Prometheus noch nicht kennt: „Observability zum Anfassen“ erklärt Scrapes und PromQL ausführlich. Hier reicht das Nötigste.
notes-api /metrics ◄── Scrape alle 15 s ── Prometheus :9090
node-exporter ◄──────────────────────┘ │
Regeln alle 15 s
│
inactive ─► pending ─(for)─► firing
Drill 1: promtool
promtool prüft Konfiguration und Regeln, bevor
Prometheus sie lädt, und stellt Abfragen von der Kommandozeile. Es liegt
im Archiv von Prometheus:
cd ~/am-lab
curl -fsSLO https://github.com/prometheus/prometheus/releases/download/\
v3.16.0/prometheus-3.16.0.linux-amd64.tar.gz
tar xzf prometheus-3.16.0.linux-amd64.tar.gz
mv prometheus-3.16.0.linux-amd64/promtool ~/.local/bin/
rm -r prometheus-3.16.0.linux-amd64*
promtool --version | head -1Erwartet:
promtool, version 3.16.0 (branch: HEAD, revision: e2e28adeee2c5883d000fc82aca6008cfbf7e96d)
Prometheus selbst läuft gleich als Container. Aus dem Archiv brauchst du nur das Werkzeug.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Prometheus-Konfiguration
mkdir -p prometheus/rules
cat > prometheus/prometheus.yml <<'EOF'
global:
scrape_interval: 15s
evaluation_interval: 15s
external_labels:
env: prod
rule_files:
- /etc/prometheus/rules/*.yml
scrape_configs:
- job_name: prometheus
static_configs:
- targets: ["localhost:9090"]
- job_name: notes-api
static_configs:
- targets: ["notes-api:8080"]
- job_name: node
static_configs:
- targets: ["node-exporter:9100"]
EOFevaluation_interval: 15s: So oft rechnet Prometheus alle Regeln durch. Der Standard ist eine Minute, im Lab willst du schneller Ergebnisse sehen.external_labels: Dieses Label hängt Prometheus an jeden Alarm, den es verschickt. An Tag 9 kommt eine zweite Umgebungdevdazu. Am Labelenverkennst du dann, woher ein Alarm stammt.node-exporterliefert Metriken der VM selbst. Du brauchst sie ab Tag 3.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Die Regeln
cat > prometheus/rules/notes.yml <<'EOF'
groups:
- name: notes
rules:
- alert: NotesApiDown
expr: up{job="notes-api"} == 0
for: 1m
labels:
severity: critical
team: notes
annotations:
summary: "notes-api auf {{ $labels.instance }} antwortet nicht"
runbook_url: "https://wiki.example.com/runbooks/notes-api-down"
- alert: NotesDbDown
expr: notes_db_up == 0
for: 1m
labels:
severity: critical
team: notes
annotations:
summary: "notes-api erreicht Postgres nicht"
- alert: NotesHighErrorRate
expr: |
sum(rate(notes_http_requests_total{path="/notes",code=~"5.."}[2m]))
/ sum(rate(notes_http_requests_total{path="/notes"}[2m])) > 0.05
for: 2m
labels:
severity: warning
team: notes
annotations:
summary: "{{ $value | humanizePercentage }} der Anfragen an /notes scheitern"
EOF
promtool check rules prometheus/rules/notes.ymlErwartet:
Checking prometheus/rules/notes.yml
SUCCESS: 3 rules found
upist eine Metrik, die Prometheus selbst für jedes Ziel schreibt: 1, wenn der Scrape klappte, sonst 0.- In Annotations sind Templates erlaubt.
$labelssind die Labels der Zeitreihe,$valueihr Wert.humanizePercentagemacht aus0.18den Text18%. - Die Fehlerquote hat kein Label
instance, weilsum()alle Zeitreihen zusammenfasst. Was nach einer Aggregation übrig bleibt, bestimmt die Labels des Alarms.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Prometheus starten
Der zweite Baustein, monitoring.yaml:
cat > monitoring.yaml <<'EOF'
services:
prometheus:
image: prom/prometheus:v3.16.0
command:
- --config.file=/etc/prometheus/prometheus.yml
- --storage.tsdb.path=/prometheus
- --web.enable-lifecycle
- --web.external-url=http://${VM_IP}:9090
volumes:
- ./prometheus:/etc/prometheus:ro
- promdata:/prometheus
ports:
- "9090:9090"
node-exporter:
image: prom/node-exporter:v1.12.1
volumes:
promdata:
EOF
echo " - monitoring.yaml" >> compose.yaml
docker compose up -d--web.enable-lifecycleerlaubt das Neuladen der Konfiguration per HTTP:curl -X POST localhost:9090/-/reload. Ohne den Schalter müsstest du den Container neu starten.--web.external-urlist die Adresse, unter der Menschen Prometheus erreichen. Prometheus baut daraus die Links in jedem Alarm. Ohne den Schalter stünde dort der Container-Name, und kein Browser fände ihn.${VM_IP}kommt aus.env.
Nach etwa 20 Sekunden:
promtool query instant http://localhost:9090 upErwartet:
up{instance="localhost:9090", job="prometheus"} => 1 @[1794856598.129]
up{instance="notes-api:8080", job="notes-api"} => 1 @[1794856598.129]
up{instance="node-exporter:9100", job="node"} => 1 @[1794856598.129]
Drei Ziele, alle mit 1. Die Weboberfläche liegt unter
http://172.16.0.61:9090, die Seite Alerts
zeigt deine Regeln.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Ein Alarm entsteht
Halte notes-api an:
docker compose stop notes-apiNach höchstens 30 Sekunden ist der Alarm pending:
promtool query instant http://localhost:9090 ALERTSErwartet:
ALERTS{alertname="NotesApiDown", alertstate="pending", instance="notes-api:8080", job="notes-api", severity="critical", team="notes"} => 1 @[1794855560.037]
ALERTS ist eine Zeitreihe, die Prometheus für jeden
aktiven Alarm schreibt. Das Label alertstate sagt, wo er
steht. Die Labels der Regel sind schon dran. Warte eine weitere Minute
und frage noch einmal:
promtool query instant http://localhost:9090 ALERTSErwartet:
ALERTS{alertname="NotesApiDown", alertstate="firing", instance="notes-api:8080", job="notes-api", severity="critical", team="notes"} => 1 @[1794855617.674]
Dieselbe Information als JSON, mit dem Zeitpunkt, seit dem die Bedingung gilt:
curl -s localhost:9090/api/v1/alerts | jq '.data.alerts[0]'Erwartet (gekürzt):
{
"labels": {
"alertname": "NotesApiDown",
"instance": "notes-api:8080",
"job": "notes-api",
"severity": "critical",
"team": "notes"
},
"state": "firing",
"activeAt": "2026-11-16T18:59:13.78407747Z",
…
}Das Label env fehlt hier noch. Prometheus hängt
external_labels erst beim Verschicken an. Starte notes-api
wieder:
docker compose start notes-apiNach dem nächsten Scrape verschwindet der Alarm.
curl -s localhost:9090/api/v1/alerts | jq '.data.alerts | length'
gibt 0 aus.
Ausprobiert: Steht
pendingnach mehr als einer Minute immer noch da, rechne nach.forzählt abactiveAt, und Prometheus prüft nur alle 15 Sekunden. Im Test wurde der Alarm 64 Sekunden nachactiveAtfiring.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Störung statt Ausfall
Die Fehlerquote braucht keinen Ausfall, nur schlechte Antworten:
NOTES_ERROR_RATE=0.3 docker compose up -d notes-apiNach gut zwei Minuten:
curl -s localhost:9090/api/v1/alerts | jq '.data.alerts[0].annotations'Erwartet:
{
"summary": "31.28% der Anfragen an /notes scheitern"
}Der Wert stammt aus $value und ändert sich mit jeder
Auswertung. Zurück zum Normalzustand:
docker compose up -d notes-apiFortschritt speichern? Kostenlos registrieren
Kontrollpunkt
promtool check rules prometheus/rules/notes.ymlErwartet: SUCCESS: 3 rules found.
curl -s localhost:9090/api/v1/rules | jq -r '.data.groups[].rules[].name'Erwartet: NotesApiDown, NotesDbDown und
NotesHighErrorRate, je eine Zeile.
promtool query instant http://localhost:9090 notes_db_upErwartet: eine Zeitreihe mit => 1.
Challenge
Schreibe eine vierte Regel NotesSlow (Schwere
warning, Team notes): Sie feuert, wenn 95 %
der Anfragen an /notes länger als 250 Millisekunden
brauchen, eine Minute lang. Löse sie mit NOTES_DELAY
aus.
Hinweis: notes-api liefert das Histogramm
notes_http_request_duration_seconds_bucket.
histogram_quantile(0.95, …) braucht die Raten pro Bucket,
zusammengefasst by (le). Neu laden mit
curl -X POST localhost:9090/-/reload.
Lösung
cat >> prometheus/rules/notes.yml <<'EOF'
- alert: NotesSlow
expr: |
histogram_quantile(0.95,
sum by (le) (rate(notes_http_request_duration_seconds_bucket{path="/notes"}[2m]))
) > 0.25
for: 1m
labels:
severity: warning
team: notes
annotations:
summary: "95 % der Anfragen an /notes dauern bis zu {{ $value | humanizeDuration }}"
EOF
promtool check rules prometheus/rules/notes.yml
curl -s -X POST localhost:9090/-/reload
NOTES_DELAY=300ms docker compose up -d notes-apiErwartet: SUCCESS: 4 rules found. Nach etwa zwei
Minuten:
curl -s localhost:9090/api/v1/alerts | jq -r '.data.alerts[].annotations.summary'Erwartet:
95 % der Anfragen an /notes dauern bis zu 487.5ms
Die Anfragen dauern 300 Millisekunden, der Alarm meldet 487,5. Prometheus kennt nur die Bucket-Grenzen, hier 0,25 und 0,5 Sekunden, und schätzt dazwischen linear. Für die Schwelle reicht das, für die Anzeige ist es grob. Zurück zum Normalzustand:
docker compose up -d notes-apiDie Regel NotesSlow bleibt für die nächsten Tage in der
Datei.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Jeder Alarm braucht ein
runbook_url. Wer nachts geweckt wird, soll nicht erst suchen müssen, was zu tun ist. - Regeln gehören ins Git und durch
promtool check rulesin der CI. Für Regeln mit Logik gibt es Unit-Tests:promtool test rules. - Alarmiere auf Symptome, die Nutzer spüren (Fehlerquote, Latenz),
nicht auf jede Ursache. Ursachen-Alarme wie
NotesDbDownhelfen bei der Diagnose und bekommen an Tag 5 eine niedrigere Stimme. forist ein Kompromiss: zu kurz, und jeder Ausreißer weckt jemanden. Zu lang, und Nutzer merken den Ausfall vor dir.