From b46f3ddd57f64769f9c691bfe2a8694fbf4b03eb Mon Sep 17 00:00:00 2001 From: Patrick Mahnke-Hartmann Date: Thu, 9 Oct 2025 22:55:17 +0200 Subject: [PATCH] Update Watcher-Agent --- Watcher-Agent.-.md | 224 ++++++++++----------------------------------- 1 file changed, 47 insertions(+), 177 deletions(-) diff --git a/Watcher-Agent.-.md b/Watcher-Agent.-.md index 7229b28..8285530 100644 --- a/Watcher-Agent.-.md +++ b/Watcher-Agent.-.md @@ -1,229 +1,99 @@ -# 🧭 Schnittstellen – Docker Service Broadcasting Agent +# Schnittstellen -## Übersicht +## Server Registrierung -Der Agent ist ein autonomer Client, der auf einem Host läuft, Docker-Container verwaltet, Metriken sammelt und mit einem zentralen Watcher-Server kommuniziert. -Der Agent arbeitet zyklisch und nutzt dabei mehrere Subsysteme: +Endpoint: /monitoring/register -1. **Registrierung & Hardware-Erkennung** -2. **Service Discovery (Containerliste)** -3. **Metrik-Übertragung (alle 30s)** -4. **ServerListener (Befehlsabruf und Ausführung)** +Beim Start des Agent, überprüft dieser, ob er bereits eine ID vom Watcher-Server zugewiesen bekommen hat. --- -## 1️⃣ Server Registrierung +## Hardware Info -**Endpoint:** -`POST /monitoring/register` +Endpoint: /monitoring/hardware-info -**Beschreibung:** -Beim Start überprüft der Agent, ob ihm bereits eine eindeutige ID vom Watcher-Server zugewiesen wurde. -Fehlt diese, registriert sich der Agent neu. +Ist der Agent erfolgreich registriert, schickt er einmalig beim starten seine Hardwareinformationen an den Server. -**Beispiel Request:** -```json -{ - "hostname": "docker-node-01", - "ip": "192.168.1.10", - "version": "1.0.3" -} -``` - -**Response:** -```json -{ - "server_id": "srv-4fd923a1", - "registered_at": "2025-10-09T10:15:00Z" -} -``` - ---- - -## 2️⃣ Hardware Info - -**Endpoint:** -`POST /monitoring/hardware-info` - -**Beschreibung:** -Nach erfolgreicher Registrierung übermittelt der Agent einmalig beim Start seine Hardwareinformationen an den Server. - -| Attribut | Beschreibung | Einheit | +| eingehender Wert | | Einheit | | --- | --- | --- | -| CpuType | Typ-Bezeichnung der eingebauten CPU | Text | -| CpuCores | Anzahl an CPU-Kernen | Anzahl | -| GpuType | Typ-Bezeichnung der Grafikkarte | Text | -| RamSize | Größe des verfügbaren Arbeitsspeichers | GB | - -**Beispiel Request:** -```json -{ - "server_id": "srv-4fd923a1", - "cpu_type": "AMD Ryzen 7 5800X", - "cpu_cores": 8, - "gpu_type": "NVIDIA RTX 3070", - "ram_size": 32 -} -``` +| CpuType| Typ-Bezeichnung des eingebauten CPU | | +| CpuCores | Anzahl an CPU-Kernen | | +| GpuType| Typ-Bezeichnung der eingebauten Grafikkarte | | +| RamSize | Größe des verfügbaren Arbeitsspeichers | | --- -## 3️⃣ Server Metrics +## Server Metrics -**Endpoint:** -`POST /monitoring/metric` +Endpoint: /monitoring/metric -**Beschreibung:** -Im 30-Sekunden-Rhythmus sendet der Agent aktuelle Systemmetriken an den Server. +Im Serverweiten Tick-Rythmus von 30 Sekunden schickt der Agent einen Metric-Payload an den Server. Dieser Payload beinhaltet die folgenden Werte: | Metric | eingehender Wert | umgerechneter Wert | | --- | --- | --- | -| CPU_LOAD | % | – | -| CPU_TEMP | °C | – | -| RAM_LOAD | % | – | -| RAM_SIZE | Byte | Gigabyte | -| GPU_LOAD | % | – | -| GPU_TEMP | °C | – | -| GPU_VRAM_LOAD | % | – | -| GPU_VRAM_SIZE | Bytes | Gigabyte | +| CPU_LOAD | prozentual | keine Umrechnung | +| CPU_TEMP | °C | keine Umrechnung | +| RAM_LOAD | prozentual | keine Umrechnung | +| RAM_SIZE | Byte | GigaByte | +| GPU_LOAD | prozentual | keine Umrechnung | +| GPU_TEMP | °C | keine Umrechnung | +| GPU_VRAM_LOAD | prozentual | keine Umrechnung | +| GPU_VRAM_SIZE | Bytes | GigaByte | | NET_RX | Bytes/s | Megabit/s | | NET_TX | Bytes/s | Megabit/s | | DISK_USAGE | Bytes | Gigabyte | | DISK_SIZE | Bytes | Gigabyte | -| DISK_TEMP | °C | – | - -**Beispiel Request:** -```json -{ - "server_id": "srv-4fd923a1", - "metrics": { - "CPU_LOAD": 12.4, - "CPU_TEMP": 53.0, - "RAM_LOAD": 64.8, - "RAM_SIZE": 32, - "GPU_LOAD": 27.3, - "GPU_TEMP": 48.0, - "GPU_VRAM_LOAD": 21.1, - "GPU_VRAM_SIZE": 8, - "NET_RX": 3.2, - "NET_TX": 1.1, - "DISK_USAGE": 125.6, - "DISK_SIZE": 500, - "DISK_TEMP": 39.0 - } -} -``` +| DISK_TEMP | °C | keine Umrechnung | --- -## 4️⃣ Service Discovery +## Service Discovery -**Endpoint:** -`POST /monitoring/service-discovery` +Endpoint: /monitoring/service-discovery -**Beschreibung:** -Beim Start übermittelt der Agent eine Liste aller auf dem Host laufenden Docker-Container. +Beim Start schickt der Agent eine Liste aller auf seinem Host laufenden Container: | Attribut | Beschreibung | Docker Variable | | --- | --- | --- | -| ServerId | ID des Hosts auf dem der Container läuft | – | -| ContainerId | Container-ID | `.Id` | -| Image | Verwendetes Image | `.Image` | -| Name | Name des Containers | `.Names[0]` | +| ServerId | ID des Hosts auf dem der Container läuft | # | +| ContainerId | ID des Containers auf dem Host | ? | +| Image | Image, das der Container verwendet | image | +| Name | Name den der Container auf dem Host hat| container_name | -**Beispiel Request:** -```json -{ - "server_id": "srv-4fd923a1", - "containers": [ - { - "container_id": "b3f9d12a9f01", - "image": "nginx:latest", - "name": "web_service" - }, - { - "container_id": "6e2b11a8c909", - "image": "mysql:8.0", - "name": "db_service" - } - ] -} -``` - -Diese Daten werden einmalig beim Start gesendet und können optional durch einen manuellen Refresh aktualisiert werden. +Diese Daten werden einmalig gesendet und können über einen manuellen refresh aktualisert werden (kommt irgendwann). +ContainerId / Image / Name werden in Form eines Container Objektes in json-Format übergeben. --- -## 5️⃣ Service Metrics *(noch nicht implementiert)* +## Service Metrics -**Geplant:** -Erweiterung um container-spezifische Metriken (CPU, RAM, I/O, Netz, Uptime) pro Docker-Container. +noch nicht implementiert --- -## 6️⃣ ServerListener +## ServerListener -**Funktion:** -Der Agent fragt periodisch beim Server nach, ob neue Befehle für ihn vorliegen. -Falls eine Nachricht vorhanden ist, wird sie abgerufen, verarbeitet und anschließend deaktiviert. +Frägt beim Server an ob eine neue (aktive) Message für den Client existiert. +Wenn eine existiert, dann kann der Client diese Anfragen und in nutzbare Daten umwandeln. +(Im Zuge der Überreichung muss die Nachricht deaktiviert werden - am besten mit einem boolean; wenn die Nachricht stets verfügbar bleibt wird sie immer wieder vom Client abgefragt) -### **Server Endpoint** -`GET /monitoring/messages/{serverId}` +Die ServerListenerDto sieht wie folgt aus: -**Response:** -```json -{ - "message_type": "restart_container", - "data": { "container_id": "b3f9d12a9f01" }, - "message_id": "msg-82d9b3f" -} -``` - -### **Message Structure** ```rust +/// Command message received from the backend server. +/// +/// ## Fields +/// - `message_type`: Type of command (e.g., "update_image", "restart_container", "stop_agent") +/// - `data`: Command payload (arbitrary JSON) +/// - `message_id`: Unique identifier for acknowledgment #[derive(Debug, Deserialize, Clone)] pub struct ServerMessage { - /// Type of command (e.g., "update_image", "restart_container", "stop_agent") pub message_type: String, - - /// Command payload (arbitrary JSON) pub data: serde_json::Value, - - /// Unique identifier for acknowledgment pub message_id: String, } ``` --- -## 7️⃣ Message Acknowledgment - -**Endpoint:** -`POST /monitoring/messages/{messageId}/ack` - -**Beschreibung:** -Nach erfolgreicher Ausführung der Nachricht deaktiviert der Agent die Nachricht auf dem Server. -Dies verhindert, dass der gleiche Befehl mehrfach ausgeführt wird. - -**Beispiel Request:** -```json -{ - "server_id": "srv-4fd923a1", - "acknowledged_at": "2025-10-09T10:22:14Z" -} -``` - -**Server-Action:** -- Setze `is_active = false` für die Nachricht -- Protokolliere den Zeitpunkt der Acknowledgment - ---- - -## 8️⃣ Message Types (Beispiele) - -| Message Type | Beschreibung | Beispiel Payload | -| --- | --- | --- | -| `restart_container` | Startet einen angegebenen Container neu | `{ "container_id": "b3f9d12a9f01" }` | -| `update_image` | Aktualisiert ein Docker-Image | `{ "image": "nginx:latest" }` | -| `stop_agent` | Stoppt den Agent-Prozess | `{}` | -| `refresh_services` | Erzwingt ein erneutes Senden der Containerliste | `{}` | +## Message Acknowledgment