Monitoring & Resilienz

Uptime Monitoring

Periodische Erreichbarkeitsprüfung aller Routen per HTTP GET oder TCP Connect — mit Statusanzeige, Response-Time-Tracking und Alarmierung bei Ausfällen.

Wie funktioniert es?

Ohne Monitoring:

Client  →  Caddy  →  Backend (abgestürzt)  →  502 Bad Gateway
                                               ↑ niemand weiß es

Mit Monitoring:

Monitor prüft alle 60s  →  Backend antwortet nicht  →  Status: DOWN (rot)
                                                       → Email-Alert
                                                       → Webhook: route_down
                                                       → Circuit Breaker reagiert

Technische Details

HTTP-Routen (Layer 7):

HTTP GET auf http(s)://<Peer-IP>:<Target-Port>/
User-Agent: GateControl-Monitor/1.0
Erwartung: Statuscode 200-399 = UP, alles andere = DOWN
Bei backend_https: HTTPS mit rejectUnauthorized: false

L4-Routen (TCP/UDP):

TCP Connect zum Backend-Port
Verbindungsaufbau erfolgreich = UP, Timeout/Fehler = DOWN

Parallelisierung: Maximal 10 gleichzeitige Checks pro Zyklus.

Gespeicherte Felder pro Route

Feld	Beschreibung
`monitoring_status`	`up`, `down` oder `unknown`
`monitoring_last_check`	Zeitpunkt der letzten Prüfung (ISO 8601)
`monitoring_response_time`	Antwortzeit in Millisekunden
`monitoring_last_change`	Zeitpunkt des letzten Statuswechsels

Einrichtung

Route erstellen oder bearbeiten
Uptime Monitoring Toggle aktivieren
Intervall konfigurieren unter Settings → Monitoring (Standard: 60 Sekunden)
Optional: Email-Alerts aktivieren (SMTP muss konfiguriert sein)
Speichern

Über die API

# Monitoring aktivieren
curl -X PUT https://gatecontrol.example.com/api/v1/routes/1 \
  -H "Authorization: Bearer gc_..." \
  -d '{"monitoring_enabled":true}'

# Manuellen Check auslösen
curl -X POST https://gatecontrol.example.com/api/v1/routes/1/check \
  -H "Authorization: Bearer gc_..."

# Monitoring-Summary abrufen
curl https://gatecontrol.example.com/api/v1/monitoring/summary \
  -H "Authorization: Bearer gc_..."

Wichtige Hinweise zum Monitoring

Der erste Check läuft 10 Sekunden nach dem Start von GateControl.
Monitoring prüft die direkte Verbindung zum Backend (Peer-IP + Port), nicht den öffentlichen Domain-Zugang.
Email-Alerts erfordern eine funktionierende SMTP-Konfiguration.
Webhook-Events: route_down und route_up.
Das Monitoring-Intervall gilt global für alle Routen.

Circuit Breaker

Blockiert Anfragen an ausgefallene Backends und gibt sofort HTTP 503 zurück — verhindert Request-Staus und schützt Backends vor Überlastung bei der Wiederherstellung.

Wie funktioniert es?

Ohne Circuit Breaker:

Client 1  →  Caddy  →  Backend (tot)  →  30s Timeout  →  502
Client 2  →  Caddy  →  Backend (tot)  →  30s Timeout  →  502
... 100 Clients warten gleichzeitig 30 Sekunden ...

Mit Circuit Breaker:

Monitoring: Backend tot (5x hintereinander)  →  Circuit Breaker: OPEN
Client 1  →  Caddy  →  503 "Service temporarily unavailable" (sofort, <1ms)
... nach 30s Timeout ...
Monitoring: Backend wieder da  →  Circuit Breaker: CLOSED
Client 3  →  Caddy  →  Backend  →  200 OK  ✓

State Machine

         Threshold Failures erreicht
 CLOSED ──────────────────────────────→ OPEN
   ↑                                      │
   │  Check erfolgreich                   │ Timeout abgelaufen
   │                                      ↓
   └──────────────────────────────── HALF-OPEN
           Check fehlgeschlagen ──→ OPEN

Zustände

Status	Caddy-Verhalten	Badge-Farbe
Closed	Normaler Betrieb, Anfragen werden weitergeleitet	Grün
Open	Caddy gibt sofort `503` mit `Retry-After` Header zurück	Rot
Half-Open	Monitoring-Check wird durchgelassen; bei Erfolg → Closed, bei Fehler → Open	Amber

Konfigurierbare Werte

Parameter	Standard	Beschreibung
Threshold	5	Aufeinanderfolgende Fehler bevor der Circuit öffnet
Timeout	30s	Sekunden im Open-Status bevor ein Half-Open-Test stattfindet

Caddy-Konfiguration im Open-Status

{
  "handle": [{
    "handler": "static_response",
    "status_code": "503",
    "body": "Service temporarily unavailable",
    "headers": { "Retry-After": ["30"] }
  }]
}

Einrichtung

Uptime Monitoring aktivieren (Voraussetzung!)
Circuit Breaker Toggle aktivieren
Threshold einstellen (z.B. 5)
Timeout einstellen (z.B. 30 Sekunden)
Speichern

# Circuit Breaker aktivieren
curl -X PUT https://gatecontrol.example.com/api/v1/routes/1 \
  -H "Authorization: Bearer gc_..." \
  -d '{"monitoring_enabled":true,"circuit_breaker_enabled":true,"circuit_breaker_threshold":5,"circuit_breaker_timeout":30}'

# Circuit Breaker manuell zurücksetzen
curl -X PATCH https://gatecontrol.example.com/api/v1/routes/1/circuit-breaker \
  -H "Authorization: Bearer gc_..." \
  -d '{"status":"closed"}'

Wichtige Hinweise zum Circuit Breaker

Monitoring ist Pflicht. Ohne Uptime Monitoring hat der Circuit Breaker keine Datenquelle.
Die Failure-Counter werden im Arbeitsspeicher gehalten. Bei Neustart starten alle Counter bei 0.
Im Open-Status werden keine Anfragen ans Backend weitergeleitet.
Der manuelle Reset setzt den Status auf closed und löscht den Failure-Counter.
Nur für HTTP-Routen verfügbar, nicht für L4.

Retry on Error

Wiederholt fehlgeschlagene Anfragen automatisch an das Backend — ideal bei kurzzeitigen Ausfällen, Backend-Neustarts oder Load Balancing mit mehreren Backends.

Wie funktioniert es?

Ohne Retry:

Client  →  Caddy  →  Backend (gerade neugestartet)  →  502 Bad Gateway  →  Client sieht Fehler

Mit Retry (3 Versuche):

Client  →  Caddy  →  Backend (Versuch 1: 502)
                  →  Backend (Versuch 2: 502)
                  →  Backend (Versuch 3: 200 OK)  →  Client sieht normale Antwort

Mit Retry + mehrere Backends:

Client  →  Caddy  →  Backend A (502)
                  →  Backend B (200 OK)  →  Client sieht normale Antwort

Technische Details

{
  "handler": "reverse_proxy",
  "upstreams": [{ "dial": "10.8.0.3:8080" }],
  "load_balancing": { "retries": 3 }
}

Parameter	Bereich	Standard	Beschreibung
Retry Count	1 – 10	3	Anzahl der Wiederholungsversuche

Use Cases

Backend-Neustart abfangen

Route app.example.com → Node.js App auf Port 3000. Beim Deployment wird die App kurz neu gestartet. Mit 3 Retries überbrückt Caddy diese Lücke.

Load Balancing mit Failover

Route api.example.com → 3 API-Server. Server B fällt aus. Caddy versucht B, bekommt einen Fehler, und leitet automatisch an C weiter.

Einrichtung

Route erstellen oder bearbeiten
Retry on Error Toggle aktivieren
Retry Count einstellen (1-10, Standard: 3)
Speichern

# Retry aktivieren mit 5 Versuchen
curl -X PUT https://gatecontrol.example.com/api/v1/routes/1 \
  -H "Authorization: Bearer gc_..." \
  -d '{"retry_enabled":true,"retry_count":5}'

Wichtige Hinweise zu Retry

POST/PUT/DELETE werden ebenfalls wiederholt. Problematisch bei nicht-idempotenten Operationen. Retry nur aktivieren wenn das Backend idempotent ist.
Die Retries erfolgen sofort hintereinander — kein exponentielles Backoff.
Retry Count von 1 bedeutet: 1 initialer Versuch + 1 Retry = maximal 2 Anfragen.
In Kombination mit Circuit Breaker: bei offenem Circuit sofort 503, keine Retries.
Nur für HTTP-Routen verfügbar, nicht für L4.

Request Mirroring

Dupliziert eingehende Anfragen asynchron an sekundäre Backends — für Shadow Deployments, Debugging und Lasttests, ohne die primäre Antwort zu beeinflussen.

Wie funktioniert es?

Ohne Mirroring:

Client  →  Caddy  →  Backend (v1)  →  Antwort an Client

Mit Mirroring:

Client  →  Caddy  →  Backend (v1)  →  Antwort an Client  ✓
                  →  Backend (v2)  →  Antwort verworfen    (Mirror)
                  →  Log-Service   →  Antwort verworfen    (Mirror)

Technische Details

{
  "handler": "mirror",
  "targets": [
    { "dial": "10.8.0.5:8080" },
    { "dial": "10.8.0.6:9090" }
  ]
}

Parameter	Wert
Max Mirror-Targets pro Route	5
Body-Buffer	Bis zu 10 MB
Timeout pro Mirror-Target	10 Sekunden
Max gleichzeitige Goroutines	100
WebSocket-Upgrades	Werden übersprungen
Anfragen > 10 MB Body	Werden ohne Body gespiegelt

Use Cases

Shadow Deployment testen

Du entwickelst Version 2 deiner API. Spiegle den Produktions-Traffic an die v2-Instanz. Vergleiche Logs und Metriken ohne Risiko.

Debugging mit Logging-Backend

Mirror-Target: ein Logging-Service der alle eingehenden Anfragen aufzeichnet. Produktions-Traffic analysieren ohne die App zu instrumentieren.

Lasttest mit echtem Traffic

Neuer Server soll den aktuellen ersetzen. Mirror den Traffic und beobachte CPU, RAM und Antwortzeiten unter realer Last.

Einrichtung

Route erstellen oder bearbeiten
Request Mirroring Toggle aktivieren
Mirror-Targets hinzufügen: Peer aus Dropdown auswählen, Port eingeben
Bis zu 5 Targets hinzufügen
Speichern

# Mirroring aktivieren mit 2 Targets
curl -X PUT https://gatecontrol.example.com/api/v1/routes/1 \
  -H "Authorization: Bearer gc_..." \
  -d '{"mirror_enabled":true,"mirror_targets":[{"peer_id":2,"port":8080},{"peer_id":3,"port":9090}]}'

Wichtige Hinweise zum Mirroring

Schreiboperationen werden gespiegelt. POST, PUT, DELETE — alles wird an die Mirror-Targets geschickt. Mirror-Targets müssen für diesen Traffic ausgelegt sein.
Mirror-Targets müssen aktive, aktivierte Peers sein.
Die Antwort des Mirror-Targets wird komplett verworfen.
Anfragen > 10 MB werden ohne Body gespiegelt.
WebSocket-Upgrade-Anfragen werden nicht gespiegelt.
Nur für HTTP-Routen verfügbar, nicht für L4.

Uptime Monitoring

Wie funktioniert es?

Technische Details

Gespeicherte Felder pro Route

Einrichtung

Über die API

Wichtige Hinweise zum Monitoring

Circuit Breaker

Wie funktioniert es?

State Machine

Zustände

Konfigurierbare Werte

Caddy-Konfiguration im Open-Status

Einrichtung

Wichtige Hinweise zum Circuit Breaker

Retry on Error

Wie funktioniert es?

Technische Details

Use Cases

Backend-Neustart abfangen

Load Balancing mit Failover

Einrichtung

Wichtige Hinweise zu Retry

Request Mirroring

Wie funktioniert es?

Technische Details

Use Cases

Shadow Deployment testen

Debugging mit Logging-Backend

Lasttest mit echtem Traffic

Einrichtung

Wichtige Hinweise zum Mirroring

Cookie Settings