Zum Inhalt

Endpoint-Monitoring

Das Endpoint-Monitoring der Polycrate API prüft kontinuierlich, ob externe und interne Dienste erreichbar sind. Es ist das Herzstück der Zustandserfassung für ManagedObjects: aus einer Sammlung regelmäßiger Probes gegen einen Endpoint ergibt sich der aggregierte state eines Objekts (OK / WARNING / CRITICAL) — und daraus wiederum Downtimes und Notifications.

Polycrate trennt dabei was geprüft wird (Endpoint) von wer prüft (Agent).

Modellübersicht

┌──────────────────┐         prüft          ┌────────────┐
│      Agent       │────────────────────────▶│  Endpoint  │
│  (CLI / Operator)│    via Assignment       │            │
└──────────────────┘                         └─────┬──────┘
                                                   │ generic FK
                                                   ▼
                                          ┌──────────────────┐
                                          │   ManagedObject  │
                                          │ (Host, LB, PoP…) │
                                          └──────────────────┘

Endpoint — was geprüft wird

Ein Endpoint beschreibt einen einzelnen Probe. Kernfelder:

Feld Zweck
name / display_name Anzeige
kind icmp, http, tcp, udp
remote_address / remote_port Ziel — Host/IP + Port
interval Sekunden zwischen Checks
timeout Max. Wartezeit pro Check
spec JSON-Detail-Konfiguration (Method, Pfad, Expected-Status, TLS-Optionen, …)
agents M2M zu Agent über EndpointAgentAssignment
content_object Generic FK auf das ManagedObject, das dieser Endpoint prüft

Kinds im Überblick:

  • icmp — klassischer Ping. Gut für Host-Reachability, braucht CAP_NET_RAW beim ausführenden Agent.
  • http — HTTP(S)-Check mit konfigurierbarem Pfad, Methode, erwarteten Statuscodes und TLS-Optionen (inkl. "self-signed akzeptieren" und TLS-Expiry-Alerts).
  • tcp — TCP-Connect-Check auf einen Port. Nützlich für Datenbanken, Message-Broker etc.
  • udp — UDP-Connect/Probe. Seltener; eingesetzt z. B. für DNS oder VPN-Gateways.

Keine weiteren Kinds

Polycrate unterstützt ausschließlich diese vier Kinds. Anwendungs-spezifische Tiefenchecks (z. B. "Redis PING"-Kommando) werden bewusst nicht im Endpoint-Monitoring abgebildet — dafür gibt es die Metrik-Pipeline und die Block-eigene Health-Check-Action.

Agent — wer prüft

Ein Agent ist der ausführende Akteur, der Endpoints tatsächlich probiert. Er meldet sich mit einem Token an der API an und pullt seine Arbeit:

Agent-Kind Beschreibung
CLI-Agent Eigener Prozess, startbar mit polycrate api agent --agent-token .... Gut für Bare-Metal, Windows, air-gapped Standorte
Operator Der Polycrate-Operator agiert im Kubernetes-Cluster als Agent mit kind=operator. Der Operator registriert sich automatisch und erscheint in der Agent-Liste

Jeder Agent sendet Heartbeats und Probe-Ergebnisse an die API. Felder wie last_seen, health_status, effective_capacity und monitored_endpoints_count machen seinen Zustand transparent.

EndpointAgentAssignment — wer prüft was

Die M2M-Zuweisung zwischen Endpoint und Agent ist explizit: ein Endpoint kann von mehreren Agents parallel geprüft werden (für Multi-Region-Monitoring), und ein Agent prüft typischerweise viele Endpoints.

Die Zuweisung kann

  • manuell erfolgen (Admin wählt pro Endpoint passende Agents),
  • automatisch über Scheduler-Logik, die freie Agent-Kapazität nutzt.

Von Probe zum Objekt-State

Ein einzelner Probe hat ein Ergebnis (up/down, Latenz, Statuscode, TLS-Details). Daraus wird pro Endpoint gerollt:

  1. Sofort — die letzten Probes bestimmen is_up und last_check am Endpoint.
  2. Zeitbasiert — VictoriaMetrics berechnet aus polycrate_io_probe_success die Uptime über 1h/24h/30d. Die Werte wandern in die Metrik-Tabs im UI (status_blocks, latency, uptime).
  3. ManagedObject-State — jeder ManagedObject mit angehängten Endpoints leitet daraus seinen eigenen state ab:
  4. OK — alle aktiven Probes erfolgreich.
  5. WARNING — einzelne Probes fehlgeschlagen / Latenz überschritten.
  6. CRITICAL — harte Schwellen verletzt → löst eine Downtime aus und Notifications an die Kontakte.

SLO / SLA

Jedes ManagedObject, das Endpoints trägt, kann SLO/SLA-Ziele definieren:

  • target_availability_percent — z. B. 99.9 %
  • actual_availability_percent — berechnet aus Probe-Historie
  • error_budget_* — abgeleitetes Fehlerbudget

Die Werte erscheinen auf dem Detail-View des Objekts und fließen in Reports.

Source-Klassifikation (API-seitig)

Wenn Endpoints aus mehreren Quellen kommen, klassifiziert die API sie, damit Ownership klar bleibt:

Source Beschreibung
api Endpoint wurde direkt in der Polycrate API angelegt (z. B. über die UI/REST)
discovery Endpoint entstand aus einer automatischen Erkennung (typisch: Operator erkennt Ingress-Objekte und legt einen Endpoint an)
manual Endpoint wurde aus dem Cluster heraus manuell erstellt

Für Ingress-basierte Discovery im Operator siehe Polycrate Operator — dort sind die Ingress-Annotationen beschrieben, mit denen man Pfade, Intervalle und Timeouts an automatisch erkannte Endpoints steuert. Aus API-Sicht sind alle drei Sources gleichwertig.

TLS-Monitoring

HTTP-Endpoints mit HTTPS erhalten automatisch TLS-Monitoring. Die API erzeugt Alerts bei:

  • Zertifikat abgelaufen / noch nicht gültig
  • Zertifikats-Chain ungültig
  • Hostname-Mismatch
  • TLS-Expiry < 30 Tagen (Schwelle pro Endpoint konfigurierbar)

Pro Endpoint kann optional ignore_tls_errors=true gesetzt werden — nötig für interne Services mit selbstsignierten Zertifikaten.

Metrik-Funktionen

Jeder Endpoint stellt die Standard-Metrik-Funktionen zur Verfügung (siehe Metriken):

Funktion Bedeutung
status_blocks Lückenlose Block-Darstellung des Probe-Ergebnisses (grün/rot/gelb)
latency Antwortzeit pro Probe über die Zeit
uptime Uptime in % pro Zeitraum

Zusätzlich exportiert der Agent Prometheus-Metriken wie polycrate_io_endpoint_up, polycrate_io_endpoint_response_time_ms, polycrate_io_endpoint_certificate_expiry_timestamp.

Multi-Region- und Multi-Agent-Monitoring

Ein Endpoint lässt sich an mehrere Agents zuweisen, die ihn parallel aus verschiedenen Regionen prüfen. Das Ergebnis:

  • Probe-Daten pro Agent — die Tabelle zeigt pro Probe, welcher Agent geantwortet hat.
  • Matrix-Darstellung — PoP-zu-PoP-Latenz als Metrik (siehe Metriken → PoP-zu-PoP-Latenz).
  • Aggregierter is_up-Wert — "Endpoint ist online" bedeutet "mindestens n Agents melden OK" (Schwelle pro Endpoint einstellbar).

Für Plattformen mit verteilten Standorten genügt es, pro Standort einen Operator oder CLI-Agent laufen zu lassen; die Zuweisung zu den Endpoints erfolgt dann zentral.

Agent-Lifecycle

Ein Agent ist selbst ein ManagedObject und hat Metrik-Funktionen wie health_status und last_seen. Bleibt der Heartbeat aus, wird der Agent auf state=CRITICAL gesetzt und erzeugt — wie jedes andere ManagedObject — eine Downtime. So erkennt die Plattform selbst, wenn ein Monitor-Standort ausfällt.

API-Endpunkte

  • GET /api/v1/endpoints/ — Endpoints auflisten, filtern nach kind, content_type (also welches Objekt geprüft wird), is_up.
  • POST /api/v1/endpoints/ — Endpoint anlegen (inkl. Agent-Zuweisung).
  • GET /api/v1/agents/ — Liste der registrierten Agents.
  • GET /api/v1/endpoint/{id}/metrics/?function=status_blocks&range=24h — Metrik pro Endpoint.

Typischer Workflow

  1. Host / LoadBalancer / Service anlegen — das Objekt, dessen Zustand du kennen willst.
  2. Endpoint(s) anhängen — einer oder mehrere Probes pro Objekt.
  3. Agent(s) zuweisen — entweder den lokalen Operator, externe CLI-Agents oder beides.
  4. SLO definieren — optional, für Availability-Reports und Fehlerbudgets.
  5. Observability — Metrik-Tabs, Downtimes, Notifications laufen automatisch.

Verwandte Themen