morz-infoboard/docs/WATCHDOG-KONZEPT.md

# Info-Board Neu - Watchdog-Konzept

## Ziel

Der Watchdog ueberwacht die kritischen Komponenten des Players und sorgt dafuer, dass der Display-Betrieb bei Abstuerzen oder Verhaengungen automatisch wiederhergestellt wird.

Die Ueberwachung erfolgt auf zwei Ebenen:

1. **Browser-Watchdog** — Ueberwachung von Chromium
2. **Agent-Watchdog** — Ueberwachung des Player-Agents

## Grundprinzipien

- Watchdogs sind extern und unabhaengig von den ueberwachten Prozessen
- Erkennung erfolgt aktiv durch Health-Checks, nicht durch Liveness-Pings
- Restart-Strategien sind progressiv und vermeiden Restart-Schleifen
- Logging ist strukturiert und fuer Admin-Diagnosen aussagekraeftig

## Browser-Watchdog (Chromium-Ueberwachung)

### Aufgaben

Der Browser-Watchdog sorgt dafuer, dass:

- Chromium staendig laeuft und antwortet
- der Renderer nicht in einer Endlosschleife haengt
- Rendering-Fehler nicht zu permanenten Schwarzbildern fuehren
- bei Chromium-Crash oder Verhaengung schnell neugestartet wird

### Health-Check-Verfahren

Der Watchdog fuehrt regelmaeßig folgende Checks durch:

#### 1. Prozess-Check

```
Existiert der Chromium-Prozess noch?
  - lsof oder ps-Abfrage auf die PID
  - Timeout: sofort bei fehlender PID
```

#### 2. HTTP-Health-Check auf localhost

```
GET http://localhost:8081/health
Timeout: 5 Sekunden
Erwartet: 200 OK und JSON-Antwort {status: "ok"}
```

Die `player-ui` muss einen einfachen `/health`-Endpunkt bereitstellen, der schnell antwortet, auch wenn die Playlist gerade verarbeitet wird.

#### 3. Rendering-Verifizierung (optional, Phase 2)

```
Screenshot-basiert erkennen, ob der Browser:
  - Fehlerseite zeigt
  - komplett schwarz ist (mehr als 95% schwarze Pixel)
  - seit mehreren Minuten denselben Content zeigt, obwohl ein Wechsel erwartet wurde
```

Diese Methode ist fuer v1 optional, wird aber fuer spaetere Verhaengungserkennung eingeplant.

### Ueberwachungs-Intervall

- Health-Check alle **30 Sekunden**
- Bei Fehler: sofort Neustart pruefen (kein Warten auf naechsten Zyklus)

### Restart-Strategie

#### Strategie: Exponentieller Backoff mit Maximum

```
Fehlerfall:
  Fehler 1: Sofort neustart (Wait 0s)
  Fehler 2: Warte 2s, versuche Restart
  Fehler 3: Warte 5s, versuche Restart
  Fehler 4: Warte 10s, versuche Restart
  Fehler 5+: Warte 30s, versuche Restart
  Nach 10 aufeinanderfolgende Fehler ohne erfolgreicher Recovery:
    - Alert an Admin (via Server-Status)
    - Overlay auf "Error" setzen
    - Watchdog-Loop verlangsamen auf 5 Min Intervall
```

#### Erfolg-Kriterium

Wenn der Health-Check 3x hintereinander erfolgreich ist:

- Backoff-Zaehler zuruecksetzen auf 0
- naechstes Fehler wieder mit sofort-Restart starten

### Logging

Jeder Watchdog-Ereignis wird protokolliert:

```json
{
  "ts": "2025-03-23T14:22:15Z",
  "component": "browser_watchdog",
  "event": "restart",
  "reason": "health_check_timeout",
  "attempt": 2,
  "next_retry_in_ms": 5000,
  "details": {
    "pid_before": 1234,
    "pid_after": 1245,
    "http_status_before": 0
  }
}
```

Logging-Ziele:

- strukturiert auf stdout/stderr (JSON)
- lokal in `/var/log/signage/watchdog.log` mit Rotation

## Agent-Watchdog (systemd-Integration)

### Aufgaben

Der Agent-Watchdog (bzw. systemd-Unit) sorgt dafuer, dass:

- der Player-Agent staendig laeuft
- nach Crash oder gewolltem Stop schnell neugestartet wird
- Restart-Grenzen ein Verhaengungsloop verhindern

### systemd-Konfiguration

```ini
[Service]
Type=simple
ExecStart=/usr/local/bin/player-agent
Restart=always
RestartSec=5
StartLimitInterval=300
StartLimitBurst=10
StandardOutput=journal
StandardError=journal
```

**Bedeutung:**

- `Restart=always` — Neustart bei jedem Exit (unabhaengig vom Exit-Code)
- `RestartSec=5` — Warte 5 Sekunden vor Neustart
- `StartLimitInterval=300` — Zaehle Restarts in einem 300s-Fenster
- `StartLimitBurst=10` — Mehr als 10 Restarts in 300s fuehrt zu systemd-Stop

Wenn `StartLimitBurst` erreicht wird:

- systemd laesst den Service stehen
- Admin wird informiert (Status-API setzt `agent_watchdog_failed`)
- manueller Eingriff oder Admin-Kommando noetig

### Health-Check durch Agent selbst

Der Agent sollte intern:

- Broker-Verbindung regelmaeßig pruefen
- Server-Sync-Status tracken
- bei kritischen Innenfehlern nicht einfach weiterlaeufen

Wenn sich der Agent selbst als unheilbar beschaedigt sieht:

- strukturiert mit Exit-Code `1` beenden (systemd startet neu)
- nicht mit `exit(0)` haengend beenden

## Verhaeltnis zu systemd

### Architektur-Entscheidung

`systemd` uebernimmt die Prozess-Wiederbelebung fuer den Agent.

Der Browser-Watchdog ist ein **separater, von systemd unabhaengiger Prozess**, weil:

- Chromium staendiger Ueberwachung bedarf (Health-Checks im 30s-Rhythmus)
- ein Systemd-Watchdog-Timer zu unverzeihlich waere (nur on/off, nicht granular)
- der Browser-Watchdog auch die Systemd-Unit selbst monitoren kann (Defensive Architektur)

### Optional: systemd WatchdogSec

Fuer den Agent ist es sinnvoll, auch systemd's Watchdog-Timer zu nutzen:

```ini
[Service]
WatchdogSec=30
ExecStart=/usr/local/bin/player-agent
```

Der Agent muesste dann periodisch `systemd-notify --ready` senden.

Das ist **optional fuer v1**, wird aber fuer spaetere Robustheit eingeplant.

## Integration mit Player-Setup

### Verzeichnisstruktur

```
/usr/local/bin/
  player-agent           — Go-Binary
  browser-watchdog       — Go-Binary oder Shell-Script

/etc/systemd/system/
  signage-agent.service
  signage-browser-watchdog.service

/var/lib/signage/
  watchdog-state.json   — letzter Zustand, Backoff-Counter

/var/log/signage/
  watchdog.log          — strukturiertes Logging
```

### Startup-Reihenfolge

1. Basis-System bootet, X11 startet
2. `signage-agent.service` startet (systemd)
3. Agent startet, prueft Konfiguration, startet `player-ui` HTTP-Server
4. `signage-browser-watchdog.service` startet (systemd)
5. Watchdog wartet initial 10s, bevor erste Checks starten
6. Agent laesst Chromium starten
7. Watchdog beginnt Health-Checks

Dieses Ordering verhindert, dass der Watchdog versucht, den Browser zu uberwachen, bevor der Agent bereit ist.

### Stopp-Reihenfolge bei Shutdown

1. systemd sendet SIGTERM an Agent und Browser-Watchdog
2. Watchdog: beendet sich, versucht nicht zu restarten
3. Agent: beendet sich, laedt Chromium herunter
4. Systemd wartet auf Completion

## Fehlerklassifizierung und Admin-Reporting

### Fehlerklassen

| Fehlerklasse | Symptom | Watchdog-Aktion | Admin-Alert |
|---|---|---|---|
| Prozess-Crash | PID weg | Sofort neustart | Nach 3x Fehlschlag |
| Health-Check-Timeout | HTTP timeout | Backoff-Restart | Nach 5x Fehlschlag |
| Rendering-Fehler | Browser zeigt Fehlerseite | Neustart | Sofort sichtbar |
| Backoff-Maximum | 10+ Fehler in 5min | Stoppen, Alert | Sofort |
| Agent-Unhealthy | Server-Sync fehlgeschlagen | Systemd-Neustart | Nach 3x Sync-Fehler |

### Admin-Oberflaeche

Status-Page und Admin-Dashboard zeigen:

```json
{
  "screen_id": "info01",
  "browser_status": {
    "pid": 1234,
    "health": "ok",
    "last_check_at": "2025-03-23T14:25:00Z",
    "restart_count_5m": 0,
    "last_error": null
  },
  "agent_status": {
    "pid": 567,
    "uptime_seconds": 3600,
    "sync_status": "ok",
    "last_sync_at": "2025-03-23T14:24:55Z",
    "systemd_restart_count": 0
  },
  "watchdog_alert": null
}
```

## Konfigurierbare Parameter

In `/etc/signage/config.yml` oder Umgebungsvariablen:

```yaml
watchdog:
  browser:
    check_interval_sec: 30
    health_check_timeout_sec: 5
    restart_backoff_steps: [0, 2, 5, 10, 30]  # Sekunden
    max_consecutive_errors: 10
    error_window_sec: 300
  agent:
    systemd_unit: "signage-agent.service"
    healthcheck_timeout_sec: 10
```

## Testing und Validierung

Testfaelle fuer den Watchdog:

1. Chromium manuell toeten (`kill -9 PID`) — sollte innerhalb 30s neustartet werden
2. Player-Agent starten/stoppen — systemd sollte neustart triggern
3. Player-UI HTTP-Server abschalten — Browser-Watchdog sollte neustarten
4. Schnelle aufeinanderfolgende Crashes — Backoff-Exponentialfunktion pruefen
5. Admin-Kommando `restart_player` — geordneter Neustart, dann Restart-Counter nicht erhoeht
6. Watchdog-Logs auf Struktur und Vollstaendigkeit pruefen

## Zusammenfassung

Der Watchdog-Ansatz ist:

- **Transparent** — klare Logging und Admin-Sichtbarkeit
- **Progressive** — Backoff statt Restart-Schleife
- **Defensiv** — mehrere Erkennungsmethoden (Prozess, HTTP, optional Rendering)
- **Integriert** — arbeitet mit systemd zusammen, nicht gegen es
- **Skalierbar** — Verfahren gilt fuer alle Player unabhaengig von Standort oder Netzwerk