Debugging und Observability

Debugging und Observability

Erster Überblick

docker compose -p hocx-dev ps
docker compose -p hocx-dev logs --tail=100 backend frontend
docker compose -p hocx-dev logs --tail=100 db redis

Bei Test/Prod den jeweiligen Projektnamen und die Release-Compose-Dateien verwenden oder ./scripts/verify_release.sh test|prod ausführen.

Healthchecks

curl --fail http://localhost:8000/api/health
curl --fail http://localhost:8001/api/health
curl --fail http://localhost:3000/login
curl --fail http://localhost:3001/

Ein erreichbarer Container ist noch kein vollständiger Funktionsnachweis. Zusätzlich Migration, Login, Datenzugriff und externe Traefik-Route prüfen.

Backend/API

• Request und HTTP-Status in Backend-/Traefik-Logs suchen.
• Fehlerdetail im Browser-Network-Tab prüfen.
• OpenAPI unter /docs gegen den erwarteten Vertrag vergleichen.
• Bei 401/403: Kundensitzung und Adminsitzung nicht verwechseln; Tenant/Rolle prüfen.
• Bei 409: konkurrierende Änderung oder fachlichen Unique-Constraint untersuchen.
• Unerwartete Serverfehler stehen zusätzlich im Platform-Admin-Panel unter Error-Logs.

Keine Secrets oder vollständigen Session-Cookies in Tickets kopieren.

Datenbank und Alembic

docker compose -p hocx-dev exec backend alembic current
docker compose -p hocx-dev exec backend alembic heads
docker compose -p hocx-dev logs --tail=150 db backend

Typische Ursachen sind mehrere Heads, fehlende Env-Werte für eine Migration, ein nicht ausgeführtes Upgrade oder unzureichende Rollenrechte. Schema nie manuell „reparieren“, ohne die entsprechende Alembic-Revision zu korrigieren oder zu ergänzen.

Redis und Kollaboration

Bei fehlender Presence oder Sperren prüfen:

1. WebSocket im Browser-Network-Tab (/api/ws/protocols/...);
2. Backend- und Redis-Containerstatus;
3. Reconnect-/Heartbeat-Verhalten im Client;
4. ob REST-Autosave unabhängig weiter funktioniert.

Redis ist ephemer. Ein Neustart darf persistierte Protokolldaten nicht verlieren, setzt aber Presence und Locks zurück.

Frontend

• Browser-Konsole und Network-Tab prüfen.
• Server-Komponentenfehler stehen im Frontend-Containerlog.
• Same-origin /api und weitergereichte Cookies kontrollieren.
• Netzwerkfehler nicht mit „nicht angemeldet“ gleichsetzen.
• Offline- und Konfliktzustand über Connectivity-/Save-Status nachvollziehen.

Uploads, Abgabebox und ClamAV

docker compose -p hocx-dev logs --tail=150 \
  abgabebox-backend abgabebox-frontend clamav

Grösse, Magic Bytes, Quota, CAPTCHA-Modus, Scanstatus, Storage-Rechte und die eingeschränkte DB-Rolle getrennt prüfen. Eine deaktivierte/unerreichbare Scan-Komponente darf in Produktion nicht unbemerkt zu unsicherem Verhalten führen.

PDF-, Export- und Word-Import

• Storage-Pfade und freien Plattenplatz prüfen;
• Backendlog auf LaTeX-/Subprozessfehler untersuchen;
• Eingabedatei und Scanstatus kontrollieren;
• Word-Import zuerst über Vorschau/Queue nachvollziehen;
• generierte Exporte dürfen gelöscht und neu erstellt werden können.

Tests und Artefakte

Bei E2E-Fehlern stehen Screenshots, Videos, Traces und Logs unter frontend/test-results/ und frontend/playwright-report/. Details und Befehle stehen im Testprozess.

Betriebsbeobachtung

Regelmässig prüfen:

• Container-Restarts und Healthchecks;
• Backend-/Traefik-Fehlerraten;
• PostgreSQL-Verbindungen und langsame Abfragen (pg_stat_statements);
• Storage- und Datenbankbelegung;
• ausstehende Scanstatus;
• Backup-Erfolg und Offsite-Synchronisation;
• Audit-/Error-Log-Retention;
• Zertifikatsablauf und Domain-Healthchecks.

Eskalationsdaten

Ein brauchbarer Fehlerbericht enthält Zeitpunkt und Zeitzone, Umgebung, Release-Tag, betroffenen Tenant ohne unnötige Personendaten, reproduzierbare Schritte, HTTP-Status, relevante bereinigte Logs und vorhandene Testartefakte.