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.

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)

{
  "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+)

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

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)

#!/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.