System-Health

Seit v0.17.3

Pipeline-Health-Endpoint, System-Tab-Banner, Status-LED in Sidebar, globaler red-Banner, E-Mail-Alarm bei sustained red > 30 Min.

Was zeigt es

/admin/system → System-Tab zeigt eine Live-Ansicht der Pipeline:

• Stream-Backlog — wie viele Messages liegen unverarbeitet im Redis-Stream?
• Insert-Rate — wie viele Check-Results werden gerade pro Sekunde geschrieben?
• DB-Free + Disk-Free — Postgres-Datenträger
• AI-Provider — antwortet, oder Fehlerstatus
• Worker-Pool — wie viele Worker laufen, wieviel Lag

Plus historische Sparklines (letzte 60 Minuten).

Endpoint

curl -H "Authorization: Bearer <ADMIN_JWT>" \
  https://deine-domain.tld/api/v1/admin/health/snapshot

{
  "stream_pending": 23,
  "insert_rate_per_s": 178,
  "db_disk_free_gb": 142.4,
  "host_disk_free_gb": 87.1,
  "ai_provider": { "name": "ollama", "ok": true, "latency_ms": 45 },
  "workers": [
    { "id": 0, "lag_s": 2, "active": true },
    { "id": 1, "lag_s": 4, "active": true }
  ],
  "status": "green",
  "evaluated_at": "2026-04-25T10:15:30Z"
}

Server-side Cache: 5 s. Aufrufe öfter sind günstig.

Status-Farben

flowchart LR
    G[grün<br/>alles ok] --> Y[gelb<br/>einzelne Werte über Schwelle]
    Y --> R[rot<br/>sustained, >5 Min]
    R --> R2[rot + Alarm<br/>>30 Min]

Wichtig: rot wird nur gezeigt, wenn der schlechte Wert 5 Minuten anhaltend überschritten ist. Einzelne Spikes verfärben nur kurz, nicht dauerhaft.

Trend-basierte Logik — kein Flackern bei kurzen Last-Spitzen.

Schwellwerte

Default:

Metrik	Gelb ab	Rot ab
Stream-Pending	> 1 000	> 5 000 (sustained 5 min)
Insert-Rate-Drop	< 50 % vom Schnitt	< 25 % (sustained)
DB-Free	< 20 %	< 10 %
Disk-Free	< 15 %	< 5 %
AI-Latency	> 10 s	> 30 s
Worker-Lag	> 30 s	> 120 s (sustained)

Konfigurierbar in system_settings.

Banner

Sidebar-LED

Kleines Status-Lämpchen oben in der Sidebar — grün, gelb oder rot. Mouse-Over zeigt Status-Text.

Globaler Banner bei rot

Wenn der Status auf rot springt (sustained), erscheint oben im Frontend ein Banner („Pipeline überlastet — Stream-Backlog steigt seit 7 Min"). Banner ist persistent, schließbar, kommt zurück bis das Problem gelöst ist.

Analog zu CriticalUpdateBanner.

E-Mail-Alarm

Bei sustained-red > 30 Minuten:

• E-Mail an alle Super-Admins
• Cooldown 6 h (kein Spam wenn das Problem länger besteht)
• Background-Task health_alerts.py

E-Mail enthält den aktuellen Snapshot + Link zum System-Tab.

Was tun bei rot

Symptom	Mögliche Ursache	Maßnahme
Stream-Pending steigt	zu wenig Worker	WORKER_REPLICAS erhöhen, Skalierung
Insert-Rate-Drop	DB-Engpass, Index-Lock	DB-Logs prüfen, Long-Running-Queries
DB-Free niedrig	Retention zu lang	TimescaleDB-Compression aktivieren, Retention senken
Disk-Free niedrig	Logs-Volumen	Log-Source-Filter prüfen
AI-Latency hoch	Provider-Last	Provider-Modell tauschen, Cache-Hits prüfen
Worker-Lag	Receiver-Burst, DB-Locks	DB-Connection-Pool, Worker-Concurrency

Setup-Wizard Sizing

Seit v0.17.3

Setup-Wizard fragt im Schritt zwischen Tenant und SMTP nach Größe (Klein / Mittel / Groß / XL). Speichert in system_settings.size_profile.

Aktuell ist die Wizard-Auswahl reine Empfehlung — der Server liest sie noch nicht aktiv aus, um Defaults zu setzen. Auto-Tuning ist Phase 2 des scaling-ux-plan und kommt später.

In der Zwischenzeit: System-Health beobachten, manuell skalieren bei Bedarf.

Performance-Baseline

50 k Checks Skalierungs-Test (auf Self-Hosting-Defaults: 1 Worker, 256 MB shared_buffers):

• ~960 checks/s sustained
• p95 ≤ 150 ms
• 0 Errors über 30 min Soak

Details: scale-test/REPORT.md im Repo. Sechs Bugs gefixt während des Tests, alle in v0.17.x deployed.

Anschluss

• Skalierung — wenn das System anschlägt
• Updates — Update-Mechanik nutzt ebenfalls Health-Check