151 lines
9.3 KiB
Markdown
151 lines
9.3 KiB
Markdown
---
|
||
type: Trading-Modul-System
|
||
_organized: true
|
||
---
|
||
|
||
# Modul-15: Monitoring-Control
|
||
|
||
**Status: FREIGEGEBEN** (20.08.2026) · Container `Modul-15-Monitoring-Control` · Image `monitoring-control:0.1.0`
|
||
|
||
## Zweck
|
||
Zentrale **technische Überwachung und Sicherheits-/Kontrollebene** des Modul-Trading-Systems.
|
||
Überwacht die Dienste M03–M14 (Health/Readiness/Erreichbarkeit) plus RabbitMQ-Queues/Consumer
|
||
und PostgreSQL und leitet daraus deterministisch einen **globalen Trading-Status**
|
||
(`ENABLED` / `PAUSED` / `HALTED` / `UNKNOWN`) ab.
|
||
|
||
**Restriktionen (Nutzer-Vorgabe):**
|
||
- **Keine KI/ML**, **keine Trading-Entscheidungen**, **keine Brokerorders**, **keine Shell-/Docker-Control-Rechte**.
|
||
- **FAIL-CLOSED:** Bei unklarem/kritischem Zustand wird Trading sicher blockiert (`HALTED`).
|
||
- M15 unerreichbar → M09 behandelt den Zustand als `HALTED` (FAIL-CLOSED, siehe M15→M09-Anbindung, FREIGEGEBEN).
|
||
- **Keine Event-Schleifen:** Events nur bei Status-Änderung, dedupliziert.
|
||
- Container wird **nicht** automatisch neu gestartet/gekillt — M15 beobachtet und entscheidet Status.
|
||
- Port 55015 **nur Docker-intern** (`expose`, kein Host-Port).
|
||
|
||
## Architektur / Datenfluss
|
||
```
|
||
M03–M14 (health/ready) RabbitMQ (Queues) PostgreSQL
|
||
│ │ │
|
||
└──────────┬────────────┴──────────────┘
|
||
▼
|
||
Modul-15-Monitoring-Control
|
||
├── probe/ MonitoringProbe (HTTP-health + RMQ passive declare + PG)
|
||
├── rules/ MonitoringRules (deterministisch, FAIL-CLOSED, versioniert)
|
||
├── core/ MonitorService (Status-Engine, Single Source of Truth)
|
||
├── storage/ Persistenz (PostgreSQL: system_health/service_health/control_event)
|
||
├── publisher/ ControlPublisher (market.control, nur bei Status-Änderung)
|
||
└── api/main.py REST-API (intern, Port 55015)
|
||
```
|
||
Status → `system_health` (append), Services → `service_health` (upsert), Änderungen → `control_event` (append-only Audit).
|
||
|
||
## API (Docker-intern, Port 55015, kein öffentliches Port-Mapping)
|
||
```
|
||
GET /health liveness
|
||
GET /health/ready readiness (postgresql)
|
||
GET /monitoring/status aktueller System-Status + Trading-Status (internes State-Modell)
|
||
GET /monitoring/services aktueller Zustand aller überwachten Services/Queues
|
||
GET /control/status Control-Status (manual_override, control_api_enabled)
|
||
GET /control/trading-state autoritativer Trading-Status für M09
|
||
POST /control manuelle Control PAUSE/HALT/RESUME (nur wenn CONTROL_API_ENABLED=true)
|
||
```
|
||
|
||
## Deterministische Regeln (Rules-Engine, Version 0.1.0)
|
||
Präzedenz strikt von oben nach unten (FAIL-CLOSED):
|
||
1. **UNKNOWN** — PostgreSQL nicht erreichbar → nicht verlässlich → `HALTED`.
|
||
2. **UNHEALTHY/HALTED** — kritische Infrastruktur (PG/RabbitMQ) oder Execution-Pfad down.
|
||
3. **DEGRADED/PAUSED** — nicht-kritische Dienste down / stale.
|
||
4. **HEALTHY/ENABLED** — alles gut.
|
||
|
||
| Bedingung | System | Trading | Reason-Code |
|
||
|---|---|---|---|
|
||
| PostgreSQL nicht erreichbar | UNHEALTHY | HALTED | `POSTGRESQL_UNREACHABLE` (+ `PERSISTENCE_FAILURE`) |
|
||
| RabbitMQ nicht erreichbar | UNHEALTHY | HALTED | `RABBITMQ_UNREACHABLE` |
|
||
| Kritischer Service down (M03–M09) | UNHEALTHY | HALTED | `CRITICAL_SERVICE_DOWN:<id>` |
|
||
| Market Data stale (> max_age) | UNHEALTHY | HALTED | `MARKET_DATA_STALE` |
|
||
| Kritische Queue Consumer fehlt | — | HALTED | `NO_CONSUMER_<queue>` |
|
||
| Kritischer Queue-Backlog ≥1000 | — | HALTED | `QUEUE_BACKLOG_CRIT:<queue>:<n>` |
|
||
| Nicht-kritische Unhealthy (Analytics/Notification) | DEGRADED | PAUSED | `CRITICAL_SERVICE_DOWN`/`NO_CONSUMER_…` |
|
||
| Queue-Backlog ≥100 / Warning | DEGRADED | PAUSED | `QUEUE_BACKLOG:<queue>:<n>` |
|
||
| Alles healthy | HEALTHY | ENABLED | — |
|
||
|
||
**FAIL-CLOSED-Hinweis:** `UNKNOWN` Trading-Status wird in der API auf `HALTED` gemappt (nie ENABLED aus unklarem Zustand).
|
||
|
||
## Events (market.control Exchange, keine Event-Schleife)
|
||
Events werden **nur bei Status-Änderung** publiziert (Idempotenz) — nie bei jedem Poll:
|
||
|
||
| Event-Typ | Routing-Key | Anlass |
|
||
|---|---|---|
|
||
| `system.degraded` | `system.degraded` | System → DEGRADED |
|
||
| `system.halted` | `system.halted` | System → UNHEALTHY (HALT) |
|
||
| `system.recovered` | `system.recovered` | System → HEALTHY |
|
||
| `trading.state` | `trading.state` | Trading-Status-Änderung |
|
||
| `service.unhealthy` | `service.unhealthy` | Einzelner Service UNHEALTHY |
|
||
|
||
## Persistenz / Audit (PostgreSQL Modul-01)
|
||
- `system_health` — append-only Zeile pro Beobachtung (aktueller Status + reason_codes).
|
||
- `service_health` — Upsert pro `service_id` (aktueller Zustand jedes Services/Queue).
|
||
- `control_event` — **append-only Audit-Trail** jeder Status-/Trading-Änderung (`STATE_CHANGE`) und manuellen Control-Aktion (`MANUAL_*`). Idempotent — eine Änderung wird **genau einmal** auditiert.
|
||
|
||
## Manuelle Control (PAUSE/HALT/RESUME)
|
||
- **Nur wenn `CONTROL_API_ENABLED=true`** (Default `false` → manuelle Control über API deaktiviert, nur Regel-getrieben).
|
||
- **RESUME wird verweigert** (`RESUME_BLOCKED_CRITICAL_CAUSE`), solange eine kritische Ursache besteht.
|
||
- Jede manuelle Aktion wird append-only in `control_event` auditiert.
|
||
|
||
## Sicherheit
|
||
- **Keine Secrets in DB/Logs/Doku/Commits** — Zugangsdaten ausschließlich via Environment (Compose).
|
||
- **Kein Docker-Socket**, **keine Shell-/Docker-Control-Rechte** (CMD=`python main.py`).
|
||
- Port 55015 nur intern (`expose`), `restart: unless-stopped`, non-root (uid 1001).
|
||
- Env: `POSTGRES_*`, `RABBITMQ_*`, `CONTROL_API_ENABLED`.
|
||
|
||
## Compose / Betrieb
|
||
- Netzwerk `trading-modules`, DB-Host `Modul-01-PostgreSQL`, RabbitMQ `Modul-02-RabbitMQ`.
|
||
- Env per Compose, Zugangsdaten nur via ENV (`POSTGRES_*`, `RABBITMQ_*`), nie hart kodiert.
|
||
|
||
## Unit-Tests
|
||
- `tests/test_monitoring.py`: **19/19 grün** — deterministische Rules, FAIL-CLOSED (PG/RabbitMQ/Critical), stale, Queue-Consumer, Idempotenz, Audit genau einmal, Recovery, Reconnect, keine Secrets, `state_version`-Inkrementierung.
|
||
|
||
## E2E-Verifikation (VPS, 20.08.2026) — 17 Szenarien
|
||
Alle 17 verifiziert (System-/Trading-Status via Loop, API `/control/trading-state` + `/monitoring/status` konsistent):
|
||
1. **Normalzustand:** `HEALTHY/ENABLED` — API, State-Modell, Loop identisch.
|
||
2. **PG-Ausfall:** `HALTED`, `POSTGRESQL_UNREACHABLE`+`PERSISTENCE_FAILURE`, Audit genau einmal.
|
||
3. **RabbitMQ-Ausfall:** `HALTED`, `RABBITMQ_UNREACHABLE`.
|
||
4. **Risk-Ausfall:** `HALTED`, `CRITICAL_SERVICE_DOWN:modul-07-risk-manager`+`NO_CONSUMER_risk.input`.
|
||
5. **Portfolio-Ausfall:** `HALTED`, `CRITICAL_SERVICE_DOWN:modul-08-portfolio-manager`.
|
||
6. **Execution-Ausfall:** `HALTED`, `CRITICAL_SERVICE_DOWN:modul-09-execution-service`.
|
||
7. **Analytics-Ausfall:** `DEGRADED` + `PAUSED` (Trading nicht vollständig kill).
|
||
8. **Notification-Ausfall:** `DEGRADED` + `PAUSED`.
|
||
9. **Market Data stale:** `HALTED`, `MARKET_DATA_STALE`; Recovery nach frischen Daten.
|
||
10. **Kritischer Consumer fehlt:** HALT-Severity korrekt (NO_CONSUMER auf kritischer Queue).
|
||
11. **Queue-Backlog:** Warning/HALT gemäß Schwelle (100/1000, Unit-getestet).
|
||
12. **Recovery:** Ursache erneut geprüft, kein Auto-RESUME solange Ursache, Status konsistent, kein Event-Spam.
|
||
13. **Manuelle Controls:** mit `CONTROL_API_ENABLED=false` sauber abgelehnt (`control_api_disabled`); Trading unangetastet.
|
||
14. **Idempotenz/Event-Flut:** stabiler Zustand → keine wiederholten SYSTEM_HALTED/SERVICE_UNHEALTHY (nur 1 Audit je Änderung).
|
||
15. **RabbitMQ-Reconnect:** automatisch (alle Recovery-Zyklen), keine Zombies, keine Eventverluste.
|
||
16. **Audit:** `control_event`/`system_health`/`service_health` vollständig + zeitlich nachvollziehbar.
|
||
17. **Security:** kein öffentlicher Port (PortBindings `{}`), kein Docker-Socket, keine Secrets im Compose/Logs.
|
||
|
||
## Bekannte Design-Hinweise (für separaten M15→M09-Vorschlag)
|
||
- **M03–M06 (Market-Data-Pipeline) sind in `CRITICAL_SERVICES`** klassifiziert. Ausfall eines einzelnen Daten-Moduls führt so zu `HALTED` (über `CRITICAL_SERVICE_DOWN`), nicht ausschließlich über `MARKET_DATA_STALE`. Das ist fachlich konservativ aber zu klären (nur Data-Pipeline vs. Execution-Pfad).
|
||
- **DEGRADED → `PAUSED`** (nicht `ENABLED`): bei Analytics/Notification-Ausfall wird Trading vorsichtig gestoppt, nicht vollständig killed. Design-Entscheidung, im Vorschlag benannt.
|
||
- **PG-Ausfall ⇒ `PERSISTENCE_FAILURE`**: ohne PG kann `control_event`-Audit nicht geschrieben werden (fachlich korrekt FAIL-CLOSED), aber Audit-Lücke im Fehlerfenster.
|
||
|
||
## Freigabe
|
||
- **FREIGEGEBEN** (20.08.2026, Nutzer-Bestätigung). Implementierung + E2E (17 Szenarien) grün.
|
||
- M09-Anbindung **umgesetzt** (Variante C, Event-Cache + HTTP-Final-Check) — siehe `modul-15-m09-anbindung-implementierung.md`, FREIGEGEBEN.
|
||
|
||
## Nächste Module
|
||
- **Modul-16 ff.** — noch Platzhalter (alpine), NICHT gestartet.
|
||
|
||
---
|
||
## Geändert
|
||
```
|
||
Geändert von: Rain Ocampo
|
||
Datum: 20.08.2026
|
||
Grund: Modul-15-Monitoring-Control dokumentiert — implementiert + E2E-verifiziert (17 Szenarien grün),
|
||
Rules/API/Events/Audit/Security dokumentiert, NICHT FREIGEGEBEN.
|
||
```
|
||
```
|
||
Geändert von: Rain Ocampo
|
||
Datum: 20.08.2026
|
||
Grund: Modul-15-Monitoring-Control auf FREIGEGEBEN gesetzt (Nutzer-Bestätigung 20.08.2026).
|
||
M15→M09-Anbindung (Variante C) als umgesetzt/FREIGEGEBEN vermerkt; Unit-Tests 19/19.
|
||
```
|