Heartbeats & API-Monitoring

Pro Heartbeat erhalten Sie eine eindeutige URL — am Ende Ihres Skripts/Cron-Jobs einen curl-Aufruf einbauen. Ausbleibender Ping innerhalb des Grace-Windows = Alert.

Zwei Erwartungsmodelle: ein festes Intervall (expected_interval_seconds, 60 s bis 24 h, Standard 300 s) ODER ein voller Cron-Ausdruck (schedule, z. B. „0 3 * * *“) mit eigener Zeitzone (timezone). Cron-Ausdrücke werden serverseitig validiert; eine gesetzte Zeitzone muss eine gültige IANA-Zone sein. Dazu kommt ein Grace-Window (grace_period_seconds, 0 bis 3600 s, Standard 60 s) als Toleranz. Bleibt der Ping bis Deadline = nächste Fälligkeit + Grace aus, gibt es einen Alert. Bei einem Cron-Plan wird die nächste Fälligkeit per Cron-Ausdruck in der Monitor-Zeitzone berechnet, sonst aus letztem Ping + Intervall.

Ein Monitor durchläuft die Status active, missed, failed und paused. Der letzte Ping wird mit Zeitstempel gespeichert; bleibt er bis zur Deadline aus, wird der Monitor auf „missed“ gesetzt und ein heartbeat_missed-Alert ausgelöst. Pausierte Monitore lösen keine Alerts aus. Bleibt ein Monitor länger als 7 Tage „missed“ (Dauer-Down ohne Reaktion), setzt eine Aufräum-Routine ihn automatisch auf „paused“ und löst hängende Heartbeat-Alerts auf — das hält den Alert-Feed sauber.

An die Ping-URL können Sie Kennzahlen anhängen: items (verarbeitete Datensätze, Alias: processed), exit_code (0 = ok, alles andere = Fehler), duration_ms (Laufzeit in Millisekunden), output bzw. msg (kurze Klartext-Notiz) und status=ok|fail. Alle Parameter sind optional und werden je Lauf gespeichert.

Sie müssen die Dauer nicht selbst rechnen: Pingen Sie zu Job-Beginn /start und am Ende /ping — XICTRAQ bildet die Differenz als Laufzeit. Alternativ liefern Sie duration_ms direkt mit. Die letzte Laufzeit erscheint als last_duration_ms in der Monitor-Übersicht.

Statt den Ping nur ausbleiben zu lassen, kann Ihr Skript einen Fehlschlag sofort melden: ein GET auf /fail setzt den Monitor auf den Status „failed“ und löst direkt einen heartbeat_failed-Alert aus — Sie warten nicht erst das Grace-Window ab. Optional hängen Sie ?msg=… als Fehlergrund, ?exit_code=… und ?items=… an. Der nächste gesunde /ping recovert den Monitor automatisch.

Mit duration_anomaly_auto lernt XICTRAQ die normale Laufzeit Ihres Jobs je Wochenstunde (Mittelwert + 3σ über ein gleitendes Fenster) und alarmiert, wenn ein Lauf deutlich aus dem Rahmen fällt — z. B. „lief 4× so lang wie sonst montags um 03:00“. Opt-in pro Heartbeat. Unabhängig davon greift immer die statische Schwelle duration_threshold_ms (in Millisekunden): setzen Sie sie nicht selbst, gilt ein Standardwert von 60000 ms (60 Sekunden), ab dem ein Lauf als langsam alarmiert wird; mit 0 schalten Sie die statische Schwelle ab. So vermeiden Sie starre Schwellen für Jobs mit schwankender Last.

Aktivieren Sie expect_output, wenn ein Lauf zwingend Output bzw. Items liefern muss. Optional setzen Sie min_items als Mindestzahl. Pingt der Job dann mit items=0 (oder unter der Mindestzahl), wertet XICTRAQ den Lauf als Leerlauf und alarmiert — auch wenn der Exit-Code 0 war. Genau der Fall „Backup lief durch, sicherte aber 0 Dateien“.

GET /api/heartbeat/{id}/history liefert die letzten Läufe als JSON — pro Lauf kind (ping | start | fail), duration_ms, exit_code, items und created_at. Praktisch, um Laufzeit-Trends oder Item-Zahlen in eigene Dashboards zu ziehen. In der Übersicht spiegeln das die Monitor-Felder last_duration_ms, last_items, last_exit_code, last_anomaly_at und last_anomaly_reason.

Pro Endpoint frei kombinierbar. JSON-Schema kann via UI eingegeben oder per JSONPath-Selektor gefiltert werden („response.users[*].email“). Regex-Matches im Body möglich.

Pro Endpoint können Sie beliebige HTTP-Header setzen — z. B. Authorization: Bearer eyJ..., X-API-Key: ... oder Basic-Auth-Werte. Header werden serverseitig gespeichert und bei jedem Check mitgesendet. Statische Tokens funktionieren direkt. Für OAuth-Flows mit kurzlebigen Tokens kombinieren Sie API-Monitoring mit einem Browser-Monitor (Login-Flow + Assert).

Pro Endpoint gibt es einen Run-now-Button (POST /api-endpoints/{id}/run), der einen sofortigen Check unabhängig vom Cron auslöst. Praktisch nach einem Deploy oder während eines offenen Alerts, um zu verifizieren ob das Problem behoben ist — ohne das nächste Intervall abzuwarten.

Statt Einzel-Request lassen sich bis zu 10 Steps verketten. Jeder Step kann Werte aus der Antwort extrahieren (JSON-Path, Header oder Regex) und sie via {{variable}} in URL, Header oder Body des nächsten Steps wiederverwenden — z. B. ein Token aus dem Login-Step. Bedingte Ausführung (run_if) überspringt Steps, wenn eine Variable fehlt; stop_on_fail stoppt die Kette beim ersten Fehlschlag. So überwachen Sie echte Auth-geschützte Workflows, nicht nur offene Health-Endpoints.

Hinterlegen Sie pro Endpoint ein JSON-Schema, prüft XICTRAQ den Antwort-Body zusätzlich gegen diesen Vertrag — und erkennt stille Schema-Änderungen („Contract Drift“): HTTP 200, aber ein Pflichtfeld fehlt, ein Typ hat sich geändert oder ein Wert verlässt den erlaubten Bereich. Verletzt der Body das Schema, gilt der Lauf als fehlgeschlagen und zählt für den Alarm wie ein Down: schlägt auch die nächste Prüfung fehl, geht derselbe Alert hinaus. Unterstützt wird eine JSON-Schema-Teilmenge: type, required, properties, items (rekursiv), enum, minimum/maximum, minLength/maxLength und format (email, uri, date-time). Ist kein Schema hinterlegt oder ist die Antwort kein gültiges JSON, wird der Vertrags-Check übersprungen — er degradiert einen Lauf also nie irrtümlich.

Pro Endpoint wählen Sie Methode (GET, POST, PUT, PATCH, DELETE, HEAD), Request-Body, Prüf-Intervall und Timeout (1–30 s, Standard 10 s). Das Mindestintervall hängt vom Plan ab: 300 s im Starter, 60 s im Business, 30 s im Agency-Plan — ein kürzer gewählter Wert wird automatisch auf das Plan-Minimum angehoben. Ein Cron prüft alle 30 Sekunden, welche Endpoints fällig sind, und führt bis zu 200 Checks pro Lauf aus. Die letzten 500 Check-Ergebnisse je Endpoint bleiben als Verlauf erhalten (HTTP-Code, Antwortzeit, Assertion-Ergebnisse), per GET /api-endpoints/{id}/history abrufbar.