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
/metricsKennzahlen im Prometheus-Textformat. Prometheus holt sie regelmäßig ab („scrape”) und speichert sie als Zeitreihen. - Ein eigenes Netz
monitoringverbindet 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 workerErwartet (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.jsonErwartet (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"
}
restartistkillmit Signal 15 (SIGTERM),stop,die,start.- Die
exec_*-Zeilen sind der Healthcheck von api: Docker führt alle 10 Sekunden/notes-api healthcheckim 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 workerErwartet (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
LIMITda. proxy hat keins und sieht den ganzen Speicher der Colima-VM – ein Kandidat fürdeploy.resources.limits. topzeigt die Prozesse mit Host-PIDs und UIDs: api und worker laufen als 65532, worker unterdocker-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"]
EOFDen 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"
EOFup 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-stoppedTop-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/nullErwartet:
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 observabilitystartet auch Grafana (Drill 8, rund 1,2 GB Image). Ohne Grafana:docker compose up -d --waitund danachdocker 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_infoist eine „Info-Metrik”: Wert immer 1, die Information steckt in den Labels.notes_http_requests_totalist ein Counter, er steigt nur. Aussagekräftig wird er mitrate(…[1m]): Anfragen pro Sekunde, gemittelt über eine Minute.- Die
/healthz-Aufrufe sind die Docker-Healthchecks,/notesmit 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: 30shä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-stoppedTop-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>__FILEaus einer Datei – das Passwort steht so nicht ininspect. - 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: prometheuslä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 Netzmonitoringmuss dafür ins Internet dürfen. - Die Härtung aus Tag 9 läuft vollständig:
read_onlymittmpfs: [/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.ymlErwartet (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/-/readyErwartet:
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 downOhne --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 logsweiter. - Prometheus braucht für Benachrichtigungen einen Alertmanager (Routing, Gruppieren, Stummschalten) und für lange Aufbewahrung Remote Write (Mimir, Thanos, VictoriaMetrics).
/metricsnie ö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_DISABLEDschaltet das Nachladen ab (live: dann auchPREINSTALL_SYNC). - Für Traces und standardisierte Metriken setzt sich OpenTelemetry durch: Anwendungen senden an einen Collector, der an Prometheus, Tempo/Jaeger und Loki verteilt.