Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 12: Observability

Ziel: Du liest Logs, Events, Ressourcen und Healthchecks des Stacks gezielt aus, und Prometheus sammelt die Metriken von notes-api und schlägt Alarm, wenn die Datenbank fehlt. · Dauer: ca. 75 min · Voraussetzung: Tag 11

Briefing

  • Compose bringt die Grundwerkzeuge mit: logs, events, stats, top, ps. Sie wirken auf alle Dienste des Projekts oder auf einzelne.
  • notes-api schreibt unter /metrics Kennzahlen im Prometheus-Textformat. Prometheus holt sie regelmäßig ab („scrape”) und speichert sie als Zeitreihen.
  • Ein eigenes Netz monitoring verbindet nur Prometheus, Grafana und api – Prometheus braucht weder web noch db zu sehen.
  • Prometheus und Grafana stehen im Profil observability (Tag 7): Sie starten nur, wenn du sie ausdrücklich verlangst.
                   Netz monitoring
 :9090 ─► prometheus ──scrape /metrics alle 5 s──► api:8080 ──► db (backend)
 :3001 ─► grafana ────► prometheus:9090              ▲
                                                     └── :8080, proxy (frontend)

Drill 1: Logs gezielt lesen

Tagesstart, Stack von Tag 11 abräumen, Stand von Tag 11 holen und starten:

source ~/compose-lab/setup/env.sh
docker compose -p notes down
mkdir -p ~/compose-lab/tag12 && cd ~/compose-lab/tag12
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag11/notes/." .
docker compose up -d --build --wait >/dev/null 2>&1
docker compose logs --tail 2 api worker
docker compose logs -t --since 30s worker

Erwartet (gekürzt, IDs und Zeiten weichen bei dir ab):

worker-1  | worker started, api=http://api:8080, interval=10s
worker-1  | summary: 0 notes, 0 words
api-1     | time=2026-10-29T22:33:49.510Z level=INFO msg="store ready" store=postgres
api-1     | time=2026-10-29T22:33:49.511Z level=INFO msg=listening addr=:8080 …
worker-1  | 2026-10-29T22:33:52.727950424Z worker started, api=http://api:8080, …
worker-1  | 2026-10-29T22:33:52.947854585Z summary: 0 notes, 0 words
Schalter Wirkung
--tail N nur die letzten N Zeilen pro Dienst
--since 30s / --until Zeitfenster, auch absolut (2026-10-29T22:00:00)
-t Zeitstempel von Docker voranstellen (für Logs ohne eigene Zeit)
-f weiterlesen, bis Strg+C
--no-log-prefix ohne dienst-1 | – die Zeile bleibt maschinenlesbar

Caddy schreibt JSON-Logs. Ohne Präfix gehen sie direkt in jq:

docker compose logs --no-log-prefix --tail 3 proxy | jq -c '{level, logger, msg}'

Erwartet (gekürzt):

{"level":"info","logger":"tls.obtain","msg":"obtaining certificate"}
{"level":"info","logger":"tls.obtain","msg":"certificate obtained successfully"}
{"level":"info","logger":"tls.obtain","msg":"releasing lock"}

logs funktioniert, weil der Logging-Treiber local (Tag 9) die Ausgaben lokal speichert und rotiert. Mit einem Treiber, der nur weiterschickt (etwa syslog), bliebe docker compose logs leer.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Events mitschneiden

docker compose events zeigt, was Docker mit den Containern des Projekts tut. Starte den Mitschnitt im Hintergrund und starte worker neu:

docker compose events --json > events.json &
sleep 1
docker compose restart worker
sleep 2
kill %1
jq -r '"\(.service)\t\(.action)"' events.json
head -1 events.json | jq '{service, action, time, signal: .attributes.signal}'
rm events.json

Erwartet (gekürzt, Zeiten weichen ab):

 Container notes-worker-1 Restarting
 Container notes-worker-1 Started
worker  kill
worker  stop
worker  die
worker  start
worker  restart
api exec_create: /notes-api healthcheck
api exec_start: /notes-api healthcheck
api exec_die
{
  "service": "worker",
  "action": "kill",
  "time": "2026-10-29T23:34:09.808461475+01:00",
  "signal": "15"
}
  • restart ist kill mit Signal 15 (SIGTERM), stop, die, start.
  • Die exec_*-Zeilen sind der Healthcheck von api: Docker führt alle 10 Sekunden /notes-api healthcheck im Container aus. So siehst du, ob und wie oft er läuft.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Ressourcen mit stats und top

docker compose stats --no-stream \
  --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.PIDs}}'
docker compose top api worker

Erwartet (gekürzt, Werte weichen ab):

NAME             CPU %     MEM USAGE / LIMIT    PIDS
notes-proxy-1    0.00%     13.5MiB / 7.737GiB   9
notes-web-1      0.00%     20.02MiB / 128MiB    11
notes-worker-1   0.10%     23.18MiB / 128MiB    2
notes-api-1      0.00%     2.188MiB / 64MiB     7
notes-db-1       0.05%     32.11MiB / 512MiB    10
SERVICE  #   UID    PID     PPID    C   STIME  TTY  TIME      CMD
api      1   65532  136589  136565  0   23:33  ?    00:00:00  /notes-api
worker   1   65532  138407  138384  0   23:34  ?    00:00:00  /sbin/docker-init -- …
worker   1   65532  138437  138407  6   23:34  ?    00:00:00  /app/.venv/bin/python …
  • Die Limits aus Tag 9 stehen als LIMIT da. proxy hat keins und sieht den ganzen Speicher der Colima-VM – ein Kandidat für deploy.resources.limits.
  • top zeigt die Prozesse mit Host-PIDs und UIDs: api und worker laufen als 65532, worker unter docker-init (init: true, Tag 9).

Fortschritt speichern? Kostenlos registrieren

Drill 4: Healthchecks auswerten

ps als JSON liefert pro Dienst State und Health; docker container inspect zeigt den Verlauf der letzten Prüfungen:

docker compose ps --format json | jq -r '"\(.Service)\t\(.State)\t\(.Health)"'
docker container inspect --format '{{json .State.Health}}' notes-api-1 \
  | jq '{Status, FailingStreak, Last: (.Log[-1] | {ExitCode, Output})}'

Erwartet (gekürzt):

api running healthy
db  running healthy
proxy   running
web running healthy
worker  running
{
  "Status": "healthy",
  "FailingStreak": 0,
  "Last": {
    "ExitCode": 0,
    "Output": ""
  }
}

proxy und worker haben keinen Healthcheck, Health bleibt leer. FailingStreak zählt Fehlschläge in Folge; erreicht er retries (Standard 3), wird der Container unhealthy. In Drill 7 siehst du das live.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Prometheus dazu

Drei Dateien unter observability/. Zuerst die Scrape-Konfiguration:

mkdir -p observability
cat > observability/prometheus.yml <<'EOF'
# prometheus.yml – Tag 12: notes-api alle 5 s abfragen
global:
  scrape_interval: 5s
  evaluation_interval: 5s

rule_files:
  - /etc/prometheus/alerts.yml

scrape_configs:
  - job_name: notes-api
    static_configs:
      - targets: ["api:8080"]
EOF

Den Pfad /metrics muss niemand angeben, er ist Standard. Dann die Alert-Regeln:

cat > observability/alerts.yml <<'EOF'
# alerts.yml – Tag 12: Alert-Regeln für notes
groups:
  - name: notes
    rules:
      - alert: NotesDBDown
        expr: notes_db_up == 0
        for: 30s
        labels:
          severity: critical
        annotations:
          summary: "notes-api erreicht die Datenbank nicht"
      - alert: NotesAPIDown
        expr: up{job="notes-api"} == 0
        for: 30s
        labels:
          severity: critical
        annotations:
          summary: "Prometheus erreicht notes-api nicht"
EOF

up setzt Prometheus selbst für jedes Target: 1, wenn der letzte Scrape klappte. notes_db_up kommt von notes-api. Die dritte Datei (Grafana) folgt in Drill 8. In compose.yaml kommen das Netz monitoring, api hängt zusätzlich daran, und der neue Dienst (vollständig in code/tag12/notes/compose.yaml):

  api:
    # … wie an Tag 11 …
    networks: [frontend, backend, monitoring]

  prometheus:
    <<: *hardening
    image: prom/prometheus:v3.15.1
    profiles: [observability]
    configs:
      - source: prometheus_yml
        target: /etc/prometheus/prometheus.yml
      - source: prometheus_alerts
        target: /etc/prometheus/alerts.yml
    volumes:
      - prometheus_data:/prometheus
    ports:
      - "127.0.0.1:${PROM_PORT:-9090}:9090"
    networks: [monitoring]
    restart: unless-stopped

Top-Level: unter networks: die Zeile monitoring: {}, unter volumes: prometheus_data: {}, unter configs: die beiden Einträge prometheus_yml und prometheus_alerts mit file: ./observability/…. Das Netz ist nicht internal, weil Prometheus einen Port veröffentlicht (Tag 2). promtool aus dem Image prüft beide Dateien:

docker pull -q prom/prometheus:v3.15.1
docker compose run --rm --no-deps --entrypoint promtool prometheus \
  check config /etc/prometheus/prometheus.yml 2>/dev/null

Erwartet:

Checking /etc/prometheus/prometheus.yml
  SUCCESS: 1 rule files found
 SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax

Checking /etc/prometheus/alerts.yml
  SUCCESS: 2 rules found

run startet Dienste mit Profil auch ohne --profile (Tag 7). Jetzt nur Prometheus starten:

docker compose up -d --wait prometheus >/dev/null 2>&1
sleep 3
curl -s localhost:9090/api/v1/targets \
  | jq -r '.data.activeTargets[] | .health, .lastError'

Erwartet:

down
Get "http://api:8080/metrics": dial tcp: lookup api on 127.0.0.11:53: no such host

up -d prometheus hat nur prometheus angefasst, api hängt noch nicht im neuen Netz, und der Name api ist dort unbekannt. Erst ein up über alles gleicht api an:

docker compose --profile observability up -d --wait 2>&1 | grep 'api-1 Recreated'
sleep 6
curl -s localhost:9090/api/v1/targets \
  | jq -r '.data.activeTargets[] | .health, .lastError'

Erwartet:

 Container notes-api-1 Recreated
up

Achtung: --profile observability startet auch Grafana (Drill 8, rund 1,2 GB Image). Ohne Grafana: docker compose up -d --wait und danach docker compose up -d --wait prometheus.

Fortschritt speichern? Kostenlos registrieren

Drill 6: PromQL über die HTTP-API

Prometheus hat eine Weboberfläche unter http://localhost:9090. Im Terminal fragst du die HTTP-API; eine kleine Funktion gibt Labels und Wert aus:

q() { curl -s localhost:9090/api/v1/query --data-urlencode "query=$1" \
  | jq -r '.data.result[] | "\(.metric | del(.__name__, .instance, .job)
           | tostring)  \(.value[1])"'
}
q notes_build_info
q notes_db_up
for i in 1 2 3; do
  curl -s -o /dev/null -w '%{http_code} ' -X POST localhost:8080/notes \
    -H "X-API-Key: $(cat secrets/api_key.txt)" -H 'Content-Type: application/json' \
    -d "{\"text\":\"Metrik $i\"}"
done
curl -s -o /dev/null -w '%{http_code}\n' -X POST localhost:8080/notes -d '{}'
sleep 6
q notes_created_total
q 'sum by (path, code) (notes_http_requests_total)'
q 'sum by (path) (rate(notes_http_requests_total[1m]))'

Erwartet (gekürzt, Zahlen weichen ab):

{"store":"postgres","version":"dev"}  1
{}  1
201 201 201 401
{}  3
{"code":"200","path":"/healthz"}  2
{"code":"200","path":"/notes"}  2
{"code":"200","path":"/metrics"}  3
{"code":"201","path":"/notes"}  3
{"code":"401","path":"/notes"}  1
{"path":"/healthz"}  0.024955306171504116
{"path":"/notes"}  0.024955306171504116
{"path":"/metrics"}  0.05814300151591712
  • notes_build_info ist eine „Info-Metrik”: Wert immer 1, die Information steckt in den Labels.
  • notes_http_requests_total ist ein Counter, er steigt nur. Aussagekräftig wird er mit rate(…[1m]): Anfragen pro Sekunde, gemittelt über eine Minute.
  • Die /healthz-Aufrufe sind die Docker-Healthchecks, /notes mit 200 die Abfragen von worker.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Alarm, wenn die Datenbank fehlt

curl -s localhost:9090/api/v1/rules \
  | jq -r '.data.groups[].rules[] | "\(.name)\t\(.health)\t\(.state)"'
docker compose stop db
sleep 50
curl -s localhost:9090/api/v1/alerts \
  | jq -r '.data.alerts[] | "\(.labels.alertname)  \(.state)  \(.activeAt)"'
docker compose ps api --format '{{.Service}} {{.Status}}'
docker container inspect --format '{{json .State.Health}}' notes-api-1 \
  | jq '{Status, FailingStreak, Last: (.Log[-1] | {ExitCode, Output})}'

Erwartet (gekürzt, Zeiten weichen ab):

NotesDBDown ok  inactive
NotesAPIDown    ok  inactive
 Container notes-db-1 Stopped
NotesDBDown  firing  2026-10-29T22:43:27.097381219Z
api Up 59 seconds (unhealthy)
{
  "Status": "unhealthy",
  "FailingStreak": 5,
  "Last": {
    "ExitCode": 1,
    "Output": ""
  }
}

Der Alarm feuert, und api ist unhealthy (drei Fehlschläge in Folge), läuft aber weiter – Docker startet unhealthy Container nicht neu (Tag 5). Prometheus kann deshalb weiter abfragen und sieht notes_db_up 0. Datenbank zurück:

docker compose start db
sleep 20
curl -s localhost:9090/api/v1/alerts | jq -c '.data.alerts'
docker compose ps api db --format '{{.Service}} {{.Status}}'

Erwartet (gekürzt):

 Container notes-db-1 Started
[]
api Up About a minute (healthy)
db Up 20 seconds (healthy)

Fragt man während der 50 Sekunden alle fünf Sekunden notes_db_up und die Alerts ab, sieht man den Übergang (Testlauf, Schleife hier nicht abgedruckt):

  5s  db_up=1  alerts=
 10s  db_up=0  alerts=
 15s  db_up=0  alerts=NotesDBDown:pending
 …
 40s  db_up=0  alerts=NotesDBDown:pending
 45s  db_up=0  alerts=NotesDBDown:firing
  • notes_db_up ändert sich erst mit dem nächsten Healthcheck, der die Datenbank prüft (alle 10 Sekunden).
  • for: 30s hält den Alarm zunächst pending; erst wenn die Bedingung 30 Sekunden lang gilt, wird er firing. Kurze Aussetzer lösen so keinen Alarm aus.
  • Prometheus wertet nur aus. Wer benachrichtigt wird (Mail, Chat, Pager), regelt ein Alertmanager – siehe Enterprise-Notiz.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Grafana (optional)

Grafana ist das größte Image im Buch. Prüf vorher den Platz:

df -h ~ | tail -1
docker pull -q grafana/grafana:13.3.0-slim
docker image ls grafana/grafana:13.3.0-slim --format '{{.Size}}'

Erwartet (gekürzt, Werte weichen ab):

/dev/disk3s5   228Gi   152Gi    19Gi    90%    1.9M  197M    1%   /System/Volumes/Data
docker.io/grafana/grafana:13.3.0-slim
1.15GB

Admin-Passwort als Secret und die Datenquelle als provisionierte Datei:

printf '%s' 'lab-grafana-pw-123' > secrets/grafana_admin.txt
cat > observability/grafana-datasource.yaml <<'EOF'
# grafana-datasource.yaml – Tag 12: Prometheus als Standard-Datenquelle
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
EOF
  grafana:
    <<: *hardening
    image: grafana/grafana:13.3.0-slim
    profiles: [observability]
    environment:
      GF_SECURITY_ADMIN_PASSWORD__FILE: /run/secrets/grafana_admin
      GF_PLUGINS_PREINSTALL_SYNC: prometheus
    secrets: [grafana_admin]
    configs:
      - source: grafana_datasource
        target: /etc/grafana/provisioning/datasources/prometheus.yaml
    volumes:
      - grafana_data:/var/lib/grafana
    tmpfs: [/tmp]
    ports:
      - "127.0.0.1:${GRAFANA_PORT:-3001}:3000"
    networks: [monitoring]
    depends_on: [prometheus]
    restart: unless-stopped

Top-Level dazu: grafana_data: {} unter volumes:, grafana_datasource mit file: ./observability/grafana-datasource.yaml unter configs:, grafana_admin mit file: ./secrets/grafana_admin.txt unter secrets:.

  • Grafana liest jede Einstellung GF_<ABSCHNITT>_<SCHLÜSSEL>__FILE aus einer Datei – das Passwort steht so nicht in inspect.
  • Das Slim-Image enthält das Prometheus-Plugin nicht. Grafana lädt beim Start eine Liste empfohlener Plugins aus dem Grafana-Katalog nach, im Hintergrund und rund 570 MB im Volume (live gesehen). GF_PLUGINS_PREINSTALL_SYNC: prometheus lädt das eine nötige Plugin vor dem Start des Webservers; ohne die Zeile meldet die Datenquelle in der ersten Minute „Plugin not registered”. Das Netz monitoring muss dafür ins Internet dürfen.
  • Die Härtung aus Tag 9 läuft vollständig: read_only mit tmpfs: [/tmp], cap_drop: [ALL], no-new-privileges, User 472 aus dem Image.
docker compose --profile observability up -d --wait >/dev/null 2>&1
sleep 5
curl -s localhost:3001/api/health | jq -c '{database, version}'
P="admin:$(cat secrets/grafana_admin.txt)"
curl -s -u "$P" localhost:3001/api/datasources | jq -c '.[] | {name, url, isDefault}'
uid=$(curl -s -u "$P" localhost:3001/api/datasources | jq -r '.[0].uid')
curl -s -u "$P" "localhost:3001/api/datasources/uid/$uid/health" | jq -r .message
curl -s -u "$P" \
  "localhost:3001/api/datasources/proxy/uid/$uid/api/v1/query?query=notes_db_up" \
  | jq -r '.data.result[0].value[1]'

Erwartet (gekürzt):

{"database":"ok","version":"13.3.0"}
{"name":"Prometheus","url":"http://prometheus:9090","isDefault":true}
Successfully queried the Prometheus API.
1

Die letzte Zeile ist dieselbe PromQL-Abfrage wie in Drill 6, diesmal durch Grafana. Im Browser: http://localhost:3001, Anmeldung admin / lab-grafana-pw-123, unter „Explore” rate(notes_http_requests_total[1m]) eingeben.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Der Stack läuft mit docker compose --profile observability up -d --wait (Grafana darf fehlen). Den vollständigen Stand findest du in code/tag12/notes/. Die Prometheus-Konfiguration ist gültig:

cd ~/compose-lab/tag12
docker compose run --rm --no-deps --entrypoint promtool prometheus \
  check config /etc/prometheus/prometheus.yml

Erwartet (gekürzt):

Checking /etc/prometheus/prometheus.yml
  SUCCESS: 1 rule files found
 SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax

Checking /etc/prometheus/alerts.yml
  SUCCESS: 2 rules found

Prometheus ist bereit:

curl -s localhost:9090/-/ready

Erwartet:

Prometheus Server is Ready.

Das Target notes-api ist oben, die Datenbank auch:

curl -s localhost:9090/api/v1/query --data-urlencode 'query=up{job="notes-api"}' \
  | jq -r '.data.result[0].value[1]'
curl -s localhost:9090/api/v1/query --data-urlencode 'query=notes_db_up' \
  | jq -r '.data.result[0].value[1]'

Erwartet:

1
1

Zwei Alert-Regeln geladen, keiner aktiv:

curl -s localhost:9090/api/v1/rules | jq -r '.data.groups[].rules[].name'
curl -s localhost:9090/api/v1/alerts | jq '.data.alerts | length'

Erwartet:

NotesDBDown
NotesAPIDown
0

api ist gesund und hängt im Netz monitoring:

docker compose ps api --format '{{.Status}} {{.Networks}}'

Erwartet (gekürzt):

Up 31 seconds (healthy) notes_backend,notes_frontend,notes_monitoring

Challenge

Lös den Alarm NotesAPIDown aus, ohne einen Container zu stoppen oder eine Datei zu ändern. Lies in Prometheus ab, warum der Scrape scheitert, und stell den Sollzustand mit einem einzigen Compose-Befehl wieder her.

Hinweis: docker network disconnect trennt einen laufenden Container von einem Netz; Compose vergleicht bei up die Netze eines Containers mit der Datei.

Lösung

docker network disconnect notes_monitoring notes-api-1
sleep 50
curl -s localhost:9090/api/v1/targets \
  | jq -r '.data.activeTargets[] | .health, .lastError'
curl -s localhost:9090/api/v1/alerts \
  | jq -r '.data.alerts[] | "\(.labels.alertname):\(.state)"'
docker compose ps api --format '{{.Service}} {{.Status}}'
docker compose up -d --wait 2>&1 | grep 'api-1 Recreated'
sleep 6
curl -s localhost:9090/api/v1/targets | jq -r '.data.activeTargets[].health'

Erwartet (gekürzt):

down
Get "http://api:8080/metrics": dial tcp: lookup api on 127.0.0.11:53: no such host
NotesAPIDown:firing
api Up 5 minutes (healthy)
 Container notes-api-1 Recreated
up

Für Docker ist api kerngesund – der Healthcheck läuft im Container und merkt nichts von einem fehlenden Netz. Nur die Sicht von außen (Prometheus) zeigt das Problem. Das ist der Grund, warum Healthchecks und Monitoring sich ergänzen und nicht ersetzen. docker compose up -d erkennt das fehlende Netz und erzeugt api neu (live geprüft in Compose 5.6.0). Zum Schluss:

docker compose --profile observability down

Ohne --profile ließe down Prometheus und Grafana stehen, und das Netz notes_monitoring bliebe mit „Resource is still in use” übrig (live geprüft).

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Logs gehören zentral gesammelt (Loki, Elasticsearch/OpenSearch, Splunk): per Logging-Treiber, besser per Agent (Fluent Bit, Vector, Grafana Alloy), der die lokalen Dateien liest – dann funktioniert docker compose logs weiter.
  • Prometheus braucht für Benachrichtigungen einen Alertmanager (Routing, Gruppieren, Stummschalten) und für lange Aufbewahrung Remote Write (Mimir, Thanos, VictoriaMetrics).
  • /metrics nie öffentlich (Tag 11 sperrt es am Proxy). Prometheus und Grafana nur mit Anmeldung, TLS und eigenen Netzen betreiben; Standardpasswörter sofort ersetzen.
  • Grafana in abgeschotteten Umgebungen: Plugins nicht aus dem Internet, sondern vorab ins Image bauen oder aus einem internen Katalog; GF_PLUGINS_PREINSTALL_DISABLED schaltet das Nachladen ab (live: dann auch PREINSTALL_SYNC).
  • Für Traces und standardisierte Metriken setzt sich OpenTelemetry durch: Anwendungen senden an einen Collector, der an Prometheus, Tempo/Jaeger und Loki verteilt.