154 lines
5.0 KiB
Markdown
154 lines
5.0 KiB
Markdown
# Deploymentcenter — Watchdog Integration für KI-Agenten
|
|
|
|
> **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.
|