Systemüberwachung und Gesundheitsprüfungen¶

Zielgruppe: Systemadministratoren, DevOps-Ingenieure

Diese Anleitung beschreibt den Gesundheitsprüfungs-Endpunkt und die Überwachungsmöglichkeiten in Bifolk.

Gesundheitsprüfungs-Endpunkt¶

Bifolk bietet einen dedizierten Gesundheitsprüfungs-Endpunkt für Container-Orchestrierung und Überwachungstools.

Endpunkt-Details¶

Endpunkt: GET /health/

Authentifizierung: Keine (öffentlicher Endpunkt)

Zweck: Container-Gesundheitsüberwachung, Load-Balancer-Gesundheitsprüfungen, Verfügbarkeitsüberwachung

Antwortformat¶

Gesundes System¶

Wenn alle Prüfungen bestanden werden, gibt der Endpunkt zurück:

{
  "status": "healthy",
  "database": "ok"
}

HTTP-Status: 200 OK

Ungesundes System¶

Wenn eine oder mehrere Prüfungen fehlschlagen, gibt der Endpunkt zurück:

{
  "status": "unhealthy",
  "database": "error",
  "error": "Database connectivity failed"
}

HTTP-Status: 503 Service Unavailable

Caching¶

Die Antwort wird 10 Sekunden gecacht, um die Datenbanklast durch häufige Gesundheitsprüfungen zu reduzieren. Dies ist sicher, da sich der Gesundheitsstatus nicht schnell ändert.

Durchgeführte Gesundheitsprüfungen¶

Der Endpunkt führt folgende Prüfungen durch:

Datenbankverbindung: Führt eine einfache Abfrage (SELECT 1) aus, um zu verifizieren, dass die Datenbankverbindung funktioniert

Anwendungsfälle¶

Docker-Gesundheitsprüfungen: Automatische Container-Gesundheitsüberwachung
Kubernetes-Probes: Liveness- und Readiness-Probes
Load-Balancer-Überwachung: Backend-Gesundheitsverifizierung
Verfügbarkeits-Überwachungsdienste: Automatisierte Verfügbarkeitsprüfungen
CI/CD-Pipelines: Bereitstellungsverifizierung

Beispielverwendung¶

Einfache Gesundheitsprüfung¶

# Gesundheitsstatus prüfen
curl http://localhost:8000/health/

# Ausgabe (gesund):
# {"status": "healthy", "database": "ok"}

Prüfung mit HTTP-Statuscode¶

# Gesundheitsstatus und HTTP-Statuscode anzeigen
curl -w "\nHTTP Status: %{http_code}\n" http://localhost:8000/health/

# Ausgabe (gesund):
# {"status": "healthy", "database": "ok"}
# HTTP Status: 200

Prüfung in Shell-Skript¶

#!/bin/bash
# Einfaches Gesundheitsprüfungsskript

response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health/)

if [ "$response" = "200" ]; then
    echo "✓ Anwendung ist gesund"
    exit 0
else
    echo "✗ Anwendung ist ungesund (HTTP $response)"
    exit 1
fi

Docker-Gesundheitsprüfung¶

Das Bifolk-Docker-Image enthält automatische Gesundheitsprüfung, die den /health/-Endpunkt verwendet.

Konfiguration¶

Die Gesundheitsprüfung läuft mit folgenden Parametern:

Intervall: 30 Sekunden zwischen Prüfungen
Timeout: 3 Sekunden pro Prüfung
Wiederholungen: 3 aufeinanderfolgende Fehlschläge, bevor als ungesund markiert
Startperiode: 40 Sekunden Schonfrist beim Container-Start

Gesundheitsstatus anzeigen¶

Container-Gesundheit prüfen¶

# Container mit Gesundheitsstatus auflisten
docker ps

# Ausgabe zeigt Gesundheitsstatus in STATUS-Spalte:
# CONTAINER ID   IMAGE           STATUS
# abc123def456   bifolk-app      Up 5 minutes (healthy)

Detaillierte Gesundheitsinformationen¶

# Detaillierte Gesundheitsprüfungsinformationen anzeigen
docker inspect bifolk-app | grep -A 10 Health

# Oder mit jq für formatierte Ausgabe:
docker inspect bifolk-app | jq '.[0].State.Health'

Gesundheitsprüfungs-Logs anzeigen¶

# Letzte 5 Gesundheitsprüfungsergebnisse anzeigen
docker inspect bifolk-app | jq '.[0].State.Health.Log[-5:]'

Bedeutung der Gesundheitsstatus¶

Gesund (Container mit Status: "healthy") - Alle Gesundheitsprüfungen bestehen - Anwendung antwortet korrekt - Datenbank ist erreichbar - Bereit, Traffic zu bedienen

Ungesund (Container mit Status: "unhealthy") - Gesundheitsprüfung gab 503-Status zurück - Datenbankverbindung fehlgeschlagen - Prüfung überschritt Timeout (3 Sekunden) - 3 aufeinanderfolgende Prüfungen fehlgeschlagen

Startend (Container mit Status: "starting") - Container kürzlich gestartet (innerhalb der 40-Sekunden-Schonfrist) - Gesundheitsprüfungen laufen, aber Fehlschläge zählen noch nicht - Ermöglicht Zeit für Anwendungsinitialisierung

Fehlerbehebung¶

Gesundheitsprüfung schlägt sofort fehl¶

Symptome: - Container wird direkt nach dem Start als ungesund markiert - Gesundheitsprüfung ist nie erfolgreich

Mögliche Ursachen & Lösungen:

Anwendung hat nicht gestartet

# Anwendungslogs prüfen
docker logs bifolk-app

# Nach Fehlern beim Start suchen
docker logs bifolk-app | grep -i error

Port nicht erreichbar

# Von innerhalb des Containers testen
docker exec bifolk-app curl http://localhost:8000/health/

# Wenn dies fehlschlägt, hört Anwendung nicht auf Port 8000

Datenbank nicht bereit

# Datenbankcontainer-Status prüfen
docker ps | grep postgres

# Verifizieren, dass Datenbank gesund ist
docker inspect bifolk-db | grep Health -A 5

Intermittierende Gesundheitsprüfungs-Fehlschläge¶

Symptome: - Gesundheitsprüfungen bestehen, dann fehlschlagen, dann wieder bestehen - Container wechselt zwischen gesund und ungesund

Mögliche Ursachen & Lösungen:

Datenbankverbindungspool-Erschöpfung

# Logs auf Datenbankverbindungsfehler prüfen
docker logs bifolk-app | grep -i "database\|connection"

# Datenbankverbindungseinstellungen überprüfen

Hohe Last verursacht Timeouts

# Systemressourcen prüfen
docker stats bifolk-app

# Gesundheitsprüfungs-Timeout bei Bedarf erhöhen

Netzwerklatenz
Timeout in docker-compose.yml erhöhen erwägen
Netzwerkprobleme zwischen Containern prüfen

Best Practices¶

Für Systemadministratoren¶

Gesundheitsprüfungsstatus überwachen
Alarme für Container einrichten, die ungesund werden
Gesundheitsprüfungs-Log-Muster überwachen
Elegante Handhabung
Ungesunde Container sollten untersucht, nicht automatisch neu gestartet werden
Logs vor Maßnahmen prüfen

Für Load-Balancer¶

Backend-Gesundheitsprüfungen konfigurieren
GET /health/ als Gesundheitsprüfungs-URL verwenden
Angemessene Prüfintervalle setzen (30 Sekunden empfohlen)
Passendes Timeout konfigurieren (3-5 Sekunden)
Antwortcodes
200: Backend ist gesund, Traffic weiterleiten
503: Backend ist ungesund, aus Pool entfernen
Andere Codes: Als ungesund betrachten

Zugriffsprotokolle¶

Bifolk schreibt HTTP-Zugriffsprotokolle im Common-Log-Format (CLF), um Administratoren die Überwachung des Anfrage-Traffics zu ermöglichen.

Protokollformat¶

Jede Anfrage erzeugt eine Protokollzeile mit folgenden Feldern:

<Benutzer-ID> <Methode> <Pfad> <Status> <Größe> <Dauer_ms>ms

Beispiel:

a3f9c12b4e01 GET /hives/ 200 12453 42ms
- GET /health/ 200 45 3ms

Feld	Beschreibung
Benutzer-ID	12-stelliges Hex-Token (pseudonymisierter SHA-256-Hash der E-Mail-Adresse des Benutzers). Anonyme Anfragen zeigen `-`.
Methode	HTTP-Methode (GET, POST, etc.)
Pfad	Anfragepfad
Status	HTTP-Antwortstatuscode
Größe	Antwort-Body-Größe in Bytes
Dauer	Anfrage-Verarbeitungszeit in Millisekunden

DSGVO-Konformität¶

Benutzeridentifikatoren in Zugriffsprotokollen werden pseudonymisiert: Die rohe E-Mail-Adresse wird durch ein 12-stelliges Hex-Token ersetzt, das aus einem SHA-256-Hash der E-Mail-Adresse abgeleitet wird. Derselbe Benutzer erzeugt immer dasselbe Token, sodass Protokolleinträge über Anfragen hinweg korreliert werden können, ohne personenbezogene Daten preiszugeben.

Note

Das pseudonymisierte Token ist ohne die ursprüngliche E-Mail-Adresse nicht umkehrbar. Protokolldateien enthalten keine E-Mail-Adressen und erfordern nicht dasselbe Niveau der DSAR-Behandlung wie PII-Datenspeicher.

Speicherort der Protokolldateien¶

Zugriffsprotokolle werden über das Django-Logging-Framework geschrieben. Standardmäßig erscheinen sie in der stdout/stderr-Ausgabe des Containers. Um sie dauerhaft zu speichern, konfigurieren Sie Ihre Container-Laufzeitumgebung so, dass Docker-Logs gesammelt werden.

# Zugriffsprotokoll-Einträge im Container-Log-Stream anzeigen
docker logs bifolk-app | grep -E "^[a-f0-9-]+ (GET|POST|PUT|PATCH|DELETE|HEAD)"

Fehler-Tracking (GlitchTip / Sentry)¶

Bifolk unterstützt die Meldung nicht behandelter Ausnahmen an einen Sentry-kompatiblen Fehler-Tracker. Als selbst gehostete Lösung empfiehlt sich GlitchTip.

Einrichtung¶

Erstellen Sie ein neues Projekt in GlitchTip (oder Sentry) und kopieren Sie den DSN aus den Projekteinstellungen.
Setzen Sie SENTRY_DSN in Ihrer bifolk.env:
```
SENTRY_DSN=https://<key>@glitchtip.example.com/<project-id>
```
Für Produktionsumgebungen verwenden Sie stattdessen die Docker-Secret-Variante:
```
SENTRY_DSN_FILE=/run/secrets/bifolk_sentry_dsn
```
Starten Sie den Container neu. Das Startprotokoll bestätigt die Aktivierung:
```
Sentry error tracking: ENABLED
```

Performance-Tracing¶

Standardmäßig ist das Performance-Tracing deaktiviert (SENTRY_TRACES_SAMPLE_RATE=0.0). Um eine Stichprobe von Anfragen aufzuzeichnen, setzen Sie einen Wert zwischen 0.0 und 1.0:

SENTRY_TRACES_SAMPLE_RATE=0.1   # 10 % der Anfragen aufzeichnen

Verwenden Sie in Produktionsumgebungen eine niedrige Sample-Rate, um den Overhead zu minimieren.

Datenschutz¶

Das SDK ist mit send_default_pii=False konfiguriert. IP-Adressen, E-Mail-Adressen und Session-Cookies der Benutzer werden nicht an den Fehler-Tracker übermittelt.