Deploymentcenter/docs/WATCHDOG_INTEGRATION_GUIDE.md

# Deploymentcenter — Watchdog Integration für KI-Agenten

> **⚠️ Geändert in Version 2.0** — Neu ist der Evaluator unter
> `GET /api/watchdog/v1/evaluate`, der per Cron minütlich laufen muss. Ohne ihn
> ändert sich der Zustand eines Monitors nur beim Eintreffen eines Heartbeats,
> ein ausgefallenes System bliebe dauerhaft `up`. `expected_interval_sec`,
> `is_muted` und `suppress_until_utc` werden jetzt ausgewertet. Neben den
> bisherigen `wd_live_`-Tokens werden auch zentrale Tokens mit dem Scope
> `watchdog:ping` akzeptiert. Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**.


> **Zielgruppe**: KI-Agenten & Softwareentwickler  
> **Zweck**: Einbindung von Heartbeat-Monitoring, Statusmeldungen und Telemetrie in Anwendungen & Serverdienste.

---

## 1. Übersicht

Der **Watchdog** in Deploymentcenter überwacht kontinuierlich den Zustand von Hosts, Diensten, Cronjobs und Proxmox-Hypervisoren. 

Anwendungen senden in regelmäßigen Abständen (standardmäßig alle 60 Sekunden) einen HTTP POST Ping an die Watchdog API. Ausbleibende Pings oder gemeldete Fehler erzeugen automatisch Warnungen im Admin-Dashboard.

---

## 2. API Endpunkt & Authentifizierung

- **URL**: `POST https://dc.mhdf.de/api/watchdog/v1/ping`
- **Content-Type**: `application/json`
- **Header**: `X-Agent-Token: <dein_watchdog_agent_token>`

### Request Body Schema (JSON)
```json
{
  "source": "srv-db-01",
  "instance": "default",
  "type": "heartbeat",
  "status": "ok",
  "message": "Service running smoothly",
  "interval": 60,
  "group": "Infrastructure",
  "os": "Ubuntu 24.04 LTS"
}
```

#### Felder:
- `source` *(string, erforderlich)*: Eindeutiger Name des Dienstes oder Hostnames (z.B. `srv-db-01` oder `PolyTrader Worker`).
- `instance` *(string, optional)*: Instanzbezeichner (Standard: `default`).
- `type` *(string)*: `heartbeat`, `host`, `hypervisor_node` oder `guest`.
- `status` *(string)*: `ok`, `warning` oder `error`.
- `message` *(string, optional)*: Status- oder Fehlermeldung.
- `interval` *(int)*: Erwarteter Abstand in Sekunden zwischen zwei Pings (Standard: `60`).
- `group` *(string, optional)*: Gruppierung im Dashboard (z.B. `Applications`, `Infrastructure`).
- `os` *(string, optional)*: Betriebssystem-Name (z.B. `.NET 8 Service`, `Debian 12`).

---

## 3. Implementierungsbeispiele

### 3.1 C# (.NET Core / .NET 8+)

```csharp
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class WatchdogHeartbeatService
{
    private static readonly HttpClient Client = new HttpClient();
    private static readonly string PingUrl = "https://dc.mhdf.de/api/watchdog/v1/ping";
    private static readonly string Token = "wd_live_token_infra_01_secure";

    public static async Task SendPingAsync(string sourceName, string status = "ok", string message = "Service active")
    {
        var payload = new
        {
            source = sourceName,
            instance = "default",
            type = "heartbeat",
            status = status,
            message = message,
            interval = 60,
            group = "Services",
            os = Environment.OSVersion.ToString()
        };

        string json = JsonSerializer.Serialize(payload);
        var request = new HttpRequestMessage(HttpMethod.Post, PingUrl)
        {
            Content = new StringContent(json, Encoding.UTF8, "application/json")
        };
        request.Headers.Add("X-Agent-Token", Token);

        try
        {
            HttpResponseMessage response = await Client.SendAsync(request);
            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("[✔] Watchdog Heartbeat erfolgreich gesendet.");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"[✖] Watchdog Ping Fehlgeschlagen: {ex.Message}");
        }
    }
}
```

### 3.2 Python 3

```python
import requests

WATCHDOG_URL = "https://dc.mhdf.de/api/watchdog/v1/ping"
AGENT_TOKEN = "wd_live_token_infra_01_secure"

def send_heartbeat(source_name, status="ok", message="Python Background Task running"):
    headers = {
        "Content-Type": "application/json",
        "X-Agent-Token": AGENT_TOKEN
    }
    payload = {
        "source": source_name,
        "instance": "default",
        "type": "heartbeat",
        "status": status,
        "message": message,
        "interval": 60,
        "group": "Python Services"
    }
    try:
        response = requests.post(WATCHDOG_URL, json=payload, headers=headers, timeout=10)
        if response.status_code == 200:
            print("[✔] Watchdog Ping OK")
    except Exception as e:
        print(f"[✖] Watchdog Ping Error: {e}")
```

### 3.3 Bash / Cronjob (Linux)

```bash
#!/usr/bin/env bash

WATCHDOG_URL="https://dc.mhdf.de/api/watchdog/v1/ping"
TOKEN="wd_live_token_infra_01_secure"
SOURCE="$(hostname)"

curl -s -X POST "$WATCHDOG_URL" \
     -H "Content-Type: application/json" \
     -H "X-Agent-Token: $TOKEN" \
     -d '{"source": "'"$SOURCE"'", "status": "ok", "message": "Hourly Backup Task Completed", "interval": 3600}'
```

---

## 4. Best Practices für KI-Agenten

1. **Heartbeat-Schleife**: Lasse in eigenständigen Hoster-Diensten einen periodischen Timer (z.B. `System.Threading.Timer` oder `BackgroundService`) alle 60s `SendPingAsync` aufrufen.
2. **Graceful Shutdown**: Sende beim Beenden des Dienstes einen Ping mit Status `stopped` oder `maintenance`.
3. **Fehlerbehandlung**: Fange Netzwerkfehler bei Watchdog-Pings stets stumm/abgefangen ab, damit der Ausfall des Monitoring-Servers niemals den Hauptanwendungsfluss unterbricht.