Zum Inhalt springen
Trainingslager IT-Trainingslager

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: 1m heiß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 -1

Erwartet:

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"]
EOF
  • evaluation_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 Umgebung dev dazu. Am Label env erkennst du dann, woher ein Alarm stammt.
  • node-exporter liefert 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.yml

Erwartet:

Checking prometheus/rules/notes.yml
  SUCCESS: 3 rules found
  • up ist eine Metrik, die Prometheus selbst für jedes Ziel schreibt: 1, wenn der Scrape klappte, sonst 0.
  • In Annotations sind Templates erlaubt. $labels sind die Labels der Zeitreihe, $value ihr Wert. humanizePercentage macht aus 0.18 den Text 18%.
  • Die Fehlerquote hat kein Label instance, weil sum() 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-lifecycle erlaubt das Neuladen der Konfiguration per HTTP: curl -X POST localhost:9090/-/reload. Ohne den Schalter müsstest du den Container neu starten.
  • --web.external-url ist 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 up

Erwartet:

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

Nach höchstens 30 Sekunden ist der Alarm pending:

promtool query instant http://localhost:9090 ALERTS

Erwartet:

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 ALERTS

Erwartet:

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

Nach dem nächsten Scrape verschwindet der Alarm. curl -s localhost:9090/api/v1/alerts | jq '.data.alerts | length' gibt 0 aus.

Ausprobiert: Steht pending nach mehr als einer Minute immer noch da, rechne nach. for zählt ab activeAt, und Prometheus prüft nur alle 15 Sekunden. Im Test wurde der Alarm 64 Sekunden nach activeAt firing.

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

Nach 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-api

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

promtool check rules prometheus/rules/notes.yml

Erwartet: 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_up

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

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

Die 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 rules in 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 NotesDbDown helfen bei der Diagnose und bekommen an Tag 5 eine niedrigere Stimme.
  • for ist ein Kompromiss: zu kurz, und jeder Ausreißer weckt jemanden. Zu lang, und Nutzer merken den Ausfall vor dir.