Update Watcher-Agent
@@ -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.
|
Endpoint: /monitoring/register
|
||||||
Der Agent arbeitet zyklisch und nutzt dabei mehrere Subsysteme:
|
|
||||||
|
|
||||||
1. **Registrierung & Hardware-Erkennung**
|
Beim Start des Agent, überprüft dieser, ob er bereits eine ID vom Watcher-Server zugewiesen bekommen hat.
|
||||||
2. **Service Discovery (Containerliste)**
|
|
||||||
3. **Metrik-Übertragung (alle 30s)**
|
|
||||||
4. **ServerListener (Befehlsabruf und Ausführung)**
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 1️⃣ Server Registrierung
|
## Hardware Info
|
||||||
|
|
||||||
**Endpoint:**
|
Endpoint: /monitoring/hardware-info
|
||||||
`POST /monitoring/register`
|
|
||||||
|
|
||||||
**Beschreibung:**
|
Ist der Agent erfolgreich registriert, schickt er einmalig beim starten seine Hardwareinformationen an den Server.
|
||||||
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:**
|
| eingehender Wert | | Einheit |
|
||||||
```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 der eingebauten CPU | Text |
|
| CpuType| Typ-Bezeichnung des eingebauten CPU | |
|
||||||
| CpuCores | Anzahl an CPU-Kernen | Anzahl |
|
| CpuCores | Anzahl an CPU-Kernen | |
|
||||||
| GpuType | Typ-Bezeichnung der Grafikkarte | Text |
|
| GpuType| Typ-Bezeichnung der eingebauten Grafikkarte | |
|
||||||
| RamSize | Größe des verfügbaren Arbeitsspeichers | GB |
|
| RamSize | Größe des verfügbaren Arbeitsspeichers | |
|
||||||
|
|
||||||
**Beispiel Request:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"server_id": "srv-4fd923a1",
|
|
||||||
"cpu_type": "AMD Ryzen 7 5800X",
|
|
||||||
"cpu_cores": 8,
|
|
||||||
"gpu_type": "NVIDIA RTX 3070",
|
|
||||||
"ram_size": 32
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3️⃣ Server Metrics
|
## Server Metrics
|
||||||
|
|
||||||
**Endpoint:**
|
Endpoint: /monitoring/metric
|
||||||
`POST /monitoring/metric`
|
|
||||||
|
|
||||||
**Beschreibung:**
|
Im Serverweiten Tick-Rythmus von 30 Sekunden schickt der Agent einen Metric-Payload an den Server. Dieser Payload beinhaltet die folgenden Werte:
|
||||||
Im 30-Sekunden-Rhythmus sendet der Agent aktuelle Systemmetriken an den Server.
|
|
||||||
|
|
||||||
| Metric | eingehender Wert | umgerechneter Wert |
|
| Metric | eingehender Wert | umgerechneter Wert |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| CPU_LOAD | % | – |
|
| CPU_LOAD | prozentual | keine Umrechnung |
|
||||||
| CPU_TEMP | °C | – |
|
| CPU_TEMP | °C | keine Umrechnung |
|
||||||
| RAM_LOAD | % | – |
|
| RAM_LOAD | prozentual | keine Umrechnung |
|
||||||
| RAM_SIZE | Byte | Gigabyte |
|
| RAM_SIZE | Byte | GigaByte |
|
||||||
| GPU_LOAD | % | – |
|
| GPU_LOAD | prozentual | keine Umrechnung |
|
||||||
| GPU_TEMP | °C | – |
|
| GPU_TEMP | °C | keine Umrechnung |
|
||||||
| GPU_VRAM_LOAD | % | – |
|
| GPU_VRAM_LOAD | prozentual | keine Umrechnung |
|
||||||
| 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 | – |
|
| DISK_TEMP | °C | keine Umrechnung |
|
||||||
|
|
||||||
**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
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 4️⃣ Service Discovery
|
## Service Discovery
|
||||||
|
|
||||||
**Endpoint:**
|
Endpoint: /monitoring/service-discovery
|
||||||
`POST /monitoring/service-discovery`
|
|
||||||
|
|
||||||
**Beschreibung:**
|
Beim Start schickt der Agent eine Liste aller auf seinem Host laufenden Container:
|
||||||
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 | Container-ID | `.Id` |
|
| ContainerId | ID des Containers auf dem Host | ? |
|
||||||
| Image | Verwendetes Image | `.Image` |
|
| Image | Image, das der Container verwendet | image |
|
||||||
| Name | Name des Containers | `.Names[0]` |
|
| Name | Name den der Container auf dem Host hat| container_name |
|
||||||
|
|
||||||
**Beispiel Request:**
|
Diese Daten werden einmalig gesendet und können über einen manuellen refresh aktualisert werden (kommt irgendwann).
|
||||||
```json
|
ContainerId / Image / Name werden in Form eines Container Objektes in json-Format übergeben.
|
||||||
{
|
|
||||||
"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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 5️⃣ Service Metrics *(noch nicht implementiert)*
|
## Service Metrics
|
||||||
|
|
||||||
**Geplant:**
|
noch nicht implementiert
|
||||||
Erweiterung um container-spezifische Metriken (CPU, RAM, I/O, Netz, Uptime) pro Docker-Container.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 6️⃣ ServerListener
|
## ServerListener
|
||||||
|
|
||||||
**Funktion:**
|
Frägt beim Server an ob eine neue (aktive) Message für den Client existiert.
|
||||||
Der Agent fragt periodisch beim Server nach, ob neue Befehle für ihn vorliegen.
|
Wenn eine existiert, dann kann der Client diese Anfragen und in nutzbare Daten umwandeln.
|
||||||
Falls eine Nachricht vorhanden ist, wird sie abgerufen, verarbeitet und anschließend deaktiviert.
|
(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**
|
Die ServerListenerDto sieht wie folgt aus:
|
||||||
`GET /monitoring/messages/{serverId}`
|
|
||||||
|
|
||||||
**Response:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"message_type": "restart_container",
|
|
||||||
"data": { "container_id": "b3f9d12a9f01" },
|
|
||||||
"message_id": "msg-82d9b3f"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Message Structure**
|
|
||||||
```rust
|
```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)]
|
#[derive(Debug, Deserialize, Clone)]
|
||||||
pub struct ServerMessage {
|
pub struct ServerMessage {
|
||||||
/// Type of command (e.g., "update_image", "restart_container", "stop_agent")
|
|
||||||
pub message_type: String,
|
pub message_type: String,
|
||||||
|
|
||||||
/// Command payload (arbitrary JSON)
|
|
||||||
pub data: serde_json::Value,
|
pub data: serde_json::Value,
|
||||||
|
|
||||||
/// Unique identifier for acknowledgment
|
|
||||||
pub message_id: String,
|
pub message_id: String,
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 7️⃣ Message Acknowledgment
|
## 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