Update Watcher-Agent
@@ -1,63 +1,229 @@
|
|||||||
#Schnittstellen
|
# 🧭 Schnittstellen – Docker Service Broadcasting Agent
|
||||||
|
|
||||||
## Server Registrierung
|
## Übersicht
|
||||||
|
|
||||||
Endpoint: /monitoring/register
|
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:
|
||||||
|
|
||||||
Beim Start des Agent, überprüft dieser, ob er bereits eine ID vom Watcher-Server zugewiesen bekommen hat.
|
1. **Registrierung & Hardware-Erkennung**
|
||||||
|
2. **Service Discovery (Containerliste)**
|
||||||
|
3. **Metrik-Übertragung (alle 30s)**
|
||||||
|
4. **ServerListener (Befehlsabruf und Ausführung)**
|
||||||
|
|
||||||
## Hardware Info
|
---
|
||||||
|
|
||||||
Endpoint: /monitoring/hardware-info
|
## 1️⃣ Server Registrierung
|
||||||
|
|
||||||
Ist der Agent erfolgreich registriert, schickt er einmalig beim starten seine Hardwareinformationen an den Server.
|
**Endpoint:**
|
||||||
Übergebene Werte:
|
`POST /monitoring/register`
|
||||||
|
|
||||||
| eingehender Wert | | Einheit |
|
**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.
|
||||||
|
|
||||||
|
**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 |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| CpuType| Typ-Bezeichnung des eingebauten CPU |
|
| CpuType | Typ-Bezeichnung der eingebauten CPU | Text |
|
||||||
| CpuCores | Anzahl an CPU-Kernen |
|
| CpuCores | Anzahl an CPU-Kernen | Anzahl |
|
||||||
| GpuType| Typ-Bezeichnung der eingebauten Grafikkarte |
|
| GpuType | Typ-Bezeichnung der Grafikkarte | Text |
|
||||||
| RamSize | Größe des verfügbaren Arbeitsspeichers |
|
| RamSize | Größe des verfügbaren Arbeitsspeichers | GB |
|
||||||
|
|
||||||
## Server Metrics
|
**Beispiel Request:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"server_id": "srv-4fd923a1",
|
||||||
|
"cpu_type": "AMD Ryzen 7 5800X",
|
||||||
|
"cpu_cores": 8,
|
||||||
|
"gpu_type": "NVIDIA RTX 3070",
|
||||||
|
"ram_size": 32
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
Endpoint: /monitoring/metric
|
---
|
||||||
|
|
||||||
Im Serverweiten Tick-Rythmus von 30 Sekunden schickt der Agent einen Metric-Payload an den Server. Dieser Payload beinhaltet die folgenden Werte:
|
## 3️⃣ Server Metrics
|
||||||
|
|
||||||
|
**Endpoint:**
|
||||||
|
`POST /monitoring/metric`
|
||||||
|
|
||||||
|
**Beschreibung:**
|
||||||
|
Im 30-Sekunden-Rhythmus sendet der Agent aktuelle Systemmetriken an den Server.
|
||||||
|
|
||||||
| Metric | eingehender Wert | umgerechneter Wert |
|
| Metric | eingehender Wert | umgerechneter Wert |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| CPU_LOAD | prozentual | keine Umrechnung|
|
| CPU_LOAD | % | – |
|
||||||
| CPU_TEMP | °C | keine Umrechnung |
|
| CPU_TEMP | °C | – |
|
||||||
| RAM_LOAD | prozentual | keine Umrechnung |
|
| RAM_LOAD | % | – |
|
||||||
| RAM_SIZE | Byte | GigaByte |
|
| RAM_SIZE | Byte | Gigabyte |
|
||||||
| GPU_LOAD | prozentual | keine Umrechnung |
|
| GPU_LOAD | % | – |
|
||||||
| GPU_TEMP | °C | keine Umrechnung|
|
| GPU_TEMP | °C | – |
|
||||||
| GPU_VRAM_LOAD | prozentual | keine Umrechnung |
|
| GPU_VRAM_LOAD | % | – |
|
||||||
| GPU_VRAM_SIZE | Bytes | GigaByte |
|
| GPU_VRAM_SIZE | Bytes | Gigabyte |
|
||||||
| NET_RX | Bytes/s | Megabit/s |
|
| NET_RX | Bytes/s | Megabit/s |
|
||||||
| NET_TX | Bytes/s | Megabit/s |
|
| NET_TX | Bytes/s | Megabit/s |
|
||||||
| DISK_USAGE | Bytes | Gigabyte |
|
| DISK_USAGE | Bytes | Gigabyte |
|
||||||
| DISK_SIZE | Bytes | Gigabyte |
|
| DISK_SIZE | Bytes | Gigabyte |
|
||||||
| DISK_TEMP | °C | keine Umrechnung |
|
| 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
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
## Service Discovery
|
---
|
||||||
|
|
||||||
Endpoint: /monitoring/service-discovery
|
## 4️⃣ Service Discovery
|
||||||
|
|
||||||
Beim Start schickt der Agent eine Liste aller auf seinem Host laufenden Container:
|
**Endpoint:**
|
||||||
|
`POST /monitoring/service-discovery`
|
||||||
|
|
||||||
|
**Beschreibung:**
|
||||||
|
Beim Start übermittelt der Agent eine Liste aller auf dem Host laufenden Docker-Container.
|
||||||
|
|
||||||
| Attribut | Beschreibung | Docker Variable |
|
| Attribut | Beschreibung | Docker Variable |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| ServerId | ID des Hosts auf dem der Container läuft | # |
|
| ServerId | ID des Hosts auf dem der Container läuft | – |
|
||||||
| ContainerId | ID des Containers auf dem Host | ? |
|
| ContainerId | Container-ID | `.Id` |
|
||||||
| Image | Image, das der Container verwendet | image |
|
| Image | Verwendetes Image | `.Image` |
|
||||||
| Name | Name den der Container auf dem Host hat| container_name |
|
| Name | Name des Containers | `.Names[0]` |
|
||||||
|
|
||||||
Diese Daten werden einmalig gesendet und können über einen manuellen refresh aktualisert werden (kommt irgendwann).
|
**Beispiel Request:**
|
||||||
ContainerId / Image / Name werden in Form eines Container Objektes in json-Format übergeben.
|
```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"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
## Service Metrics
|
Diese Daten werden einmalig beim Start gesendet und können optional durch einen manuellen Refresh aktualisiert werden.
|
||||||
noch nicht implementiert
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5️⃣ Service Metrics *(noch nicht implementiert)*
|
||||||
|
|
||||||
|
**Geplant:**
|
||||||
|
Erweiterung um container-spezifische Metriken (CPU, RAM, I/O, Netz, Uptime) pro Docker-Container.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6️⃣ 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.
|
||||||
|
|
||||||
|
### **Server Endpoint**
|
||||||
|
`GET /monitoring/messages/{serverId}`
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message_type": "restart_container",
|
||||||
|
"data": { "container_id": "b3f9d12a9f01" },
|
||||||
|
"message_id": "msg-82d9b3f"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### **Message Structure**
|
||||||
|
```rust
|
||||||
|
#[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 | `{}` |
|
||||||
|
|||||||
Reference in New Issue
Block a user