Heim/Dokumente/Überwachung

Überwachungsvertrag

Vertragsversion 2.0.0 · Payload schema_version 2.0 · Test-/kostenpflichtige Pläne

Durch die Überwachung wird Ihre Nebenstelle ständig überwacht: Eine Live-Ampel leuchtet seine Karte in der Liste, eine Basis Überwachung Tab rein Details und eine separate Telegram-Statusmeldung mit Kantenwarnungen. Es verbindet zwei unabhängig aktivierte Komponenten: a Herzschlag drücken (Ein Agent auf dem Host Ihres Dienstes berichtet über einen erklärten Zeitplan; Stille ist selbst ein Signal) und Verfügbarkeits-Pings (Das Gremium prüft Ihre öffentliche URLs für Verfügbarkeit).

1. Funktionsweise (zwei Komponenten, ein Licht)

• Herzschlag drücken: ein Cron-Skript auf Ihrem Host (z. B. ein angepasstes monitor.sh) POSTs ein v2-Metrikbericht an das Panel im Intervall du hast erklärt. Jeder Bericht muss das vorbehaltene overall-Urteil tragen. Verpasste Meldungen eskalieren das Licht (Totmannschalter): Wenn der Host das Netzwerk verlässt oder Cron stirbt, Sie sehen es genau daran, dass die Anrufe aufhören.
• Verfügbarkeits-Pings: Das Gremium selbst befragt regelmäßig die Öffentlichkeit URLs, die Sie konfigurieren (Site, API, Dokumente) und nur die Verfügbarkeit prüfen, niemals die Inhalt. Kein Agent erforderlich, ein URL reicht aus.

Eine Erweiterung ist „auf Überwachung“, wenn die Überwachung aktiviert ist und mindestens eine Komponente konfiguriert ist. Ansonsten zeigt seine Karte einen neutralen grauen Punkt.

1b. Heartbeats und der Slot-Pool

Die Überwachung erfolgt auf der Nebenstellenebene als zwei unabhängige flache Listen, die gemeinsam genutzt werden ein Slot-Pool: Herzschläge (Push-Produzenten, früher „Stände“) und Verfügbarkeits-Pings (Schecks ziehen). Eine Erweiterung kann mehrere haben heartbeats – zum Beispiel ein Hauptwirt und ein bezahlter Arbeiter. Jeder Herzschlag drängt Berichte mit seinem eigener Inhaber-Token und erklärt sich zu eigen Präsentation (Tabs, Abschnitte und Telegram Zeilen) über seinen label. Betriebszeit-Pings sind eine separate flache Liste, die der Erweiterung gehört und nicht unter einer verschachtelt ist Herzschlag. Das Panel verschmilzt alles zu einem Gesamtlicht (Worst-of), einem Detailoberfläche und eine zusammenfassende Telegram-Meldung.

Heartbeats und Pings teilen sich eine einzige Pro-Erweiterung Slot-Pool: eins Heartbeat kostet einen Slot, ein aktiver Ping kostet einen Slot und ihre Summe darf nicht den max_slots des Plans überschreiten (Testversion 3 · Studio 10 · Flotte 25). Bei Überschreitung des Pools wird 409 slot_limit zurückgegeben. nach einem Downgrade die Selbstbeteiligung ist ausgesetzt (Pings zuerst, Heartbeats zuletzt). Die Antwort trägt slots_used und max_slots, damit die Benutzeroberfläche das Budget anzeigen kann.

2. Die Ampel

Das Aggregat ist das das Schlimmste Rollup über alle aktivierten Elemente hinweg Die Herzschlagkomponente und das Licht jedes aktiven Pings, wobei die Schweregrade wie folgt geordnet sind ok < warn < crit. Die Komponente eines Herzschlags ist max(reported, watchdog): reported ist der Schweregrad des overall Metrik vom letzten akzeptiert Bericht; watchdog ist ein Frische-Boden, der aus dem eigenen Empfang des Panels berechnet wird Uhr (Versatz der Agentenuhr ist harmlos).

Der Schweregrad ist kanonisch ok | warn | crit. Freundliche Aliase werden bei der Aufnahme normalisiert: warning wird warn; error und critical werden zu crit.

3. Watchdog (verpasste Herzschläge)

Sie geben das erwartete Berichtsintervall (60 Sekunden bis 24 Stunden) an, wenn Sie das aktivieren Herzschlag. Der Wachhund stuft dann das Licht durch Frische, mit ein grace = max(60s, 25% of the interval) um Cron- und Netzwerk-Jitter zu absorbieren:

Ein abgelehnter Bericht (401/422/429) aktualisiert den Watchdog nie, also ist er kaputt Agent eskaliert ehrlich; Der letzte Ablehnungsgrund ist im sichtbar Überwachungseinstellungen. Die Wiederherstellung erfolgt sofort: Der erste akzeptierte Bericht wird neu berechnet das Licht sofort.

4. Verfügbarkeits-Pings

Ein Ping ist eine benannte Verfügbarkeitsprüfung eines öffentlichen https URL. Das Panel führt GET mit einem 10s Timeout, folgt höchstens 5 Weiterleitungen, liest keinen Körper über eine minimale Grenze hinaus und behandelt a endgültiger 2xx-Klassenstatus als Erfolg (204 und 206 zählen auch). Ein Finale 3xx (Umleitungsschleife oder -limit), 4xx, 5xx, Zeitüberschreitung oder DNS/TLS/Netzwerkfehler ist ein Misserfolg. Eine fehlgeschlagene Prüfung wird durch einen erneuten Versuch nach ca. 15 Sekunden bestätigt, bevor sie zählt. Dadurch werden einzelne Netzwerkfehler absorbiert.

Ping-Ergebnisse werden als Erstanbieter-Metriken ping:<name> im angezeigt Pings Abschnitt (Uptime) der Basis Überwachung tab und als reservierte Telegram-Zeile pings: 🟢 api 210ms · 🟢 site 90ms · 🔴 docs (timeout). Die Anzahl der Pings pro Nebenstelle und das Mindestintervall hängen vom Plan ab:

Die Überwachung als Ganzes ist nur testweise/kostenpflichtig; Das minimale Heartbeat-Intervall beträgt bei allen Plänen 60 Sekunden.

5. Erweiterung der Überwachung

In der Erweiterung Einstellungen, Überwachungsblock:

• Schalten Sie die Überwachung ein (Testversion/kostenpflichtige Pläne).
• Herzschlag: aktivieren Sie es und deklarieren Sie das Berichtsintervall; das Panel gibt einen Inhaber aus Überwachungstoken, genau einmal angezeigt (drehen). jederzeit; der alte Token bekommt sofort 401). Platzieren Sie den Token und den Endpunkt URL in die Umgebung Ihres Agenten.
• Pings: Benannte öffentliche URLs hinzufügen (z. B. site, api, docs) mit einem Ping-Intervall bis zum Planlimit.
• Telegram: Aktivieren Sie die Überwachung der Zustellung und legen Sie optional eine fest separate Gruppe/Chat.

6. Das Berichtsformat

Der Bericht ist die gleiche metadatengesteuerte v2-Nutzlast wie der Custom-Metrics-Vertrag (Registerkarten, Abschnitte, Telegram Zeilen, Metriken), gepusht POST /api/v1/monitoring/report mit Authorization: Bearer <monitoring token>. Überwachung fügt hinzu reservierte IDs:

Grenzen: maximal Nutzlast 64 KB, höchstens 200 Metriken, höchstens 2 Berichte pro Minute pro Quelle (Überschuss erhält 429 und tut es zählen nicht als Herzschlag).

6.1. Beispielbericht

{
  "schema_version": "2.0",
  "generated_at": "2026-07-12T10:19:58Z",
  "tabs":     [ { "id": "stand", "title": "Stand", "order": 5, "icon": "server" } ],
  "sections": [ { "tab": "stand",      "id": "docker", "title": "Docker", "order": 0 },
                { "tab": "monitoring", "id": "host",   "title": "Host",   "order": 10 } ],
  "telegram": { "header": "{sev} {name} monitoring",
                "lines": [ { "id": "host",   "order": 0, "prefix": "🖥 " },
                           { "id": "docker", "order": 1, "prefix": "📦 " } ] },
  "metrics": [
    { "id": "overall", "kind": "status", "state": "ok", "severity": "ok" },

    { "id": "issues", "kind": "list",
      "value": { "items": [ { "text": "RAM 91% (7.1/7.8G)", "severity": "warn" } ] },
      "dashboard": { "show": true, "tab": "monitoring", "section": "host", "order": 0,
                     "render": "list", "name": "Issues" },
      "telegram":  { "show": false } },

    { "id": "ram", "kind": "percent", "label": "RAM", "value": 91, "severity": "warn",
      "dashboard": { "show": true, "tab": "monitoring", "section": "host", "order": 1,
                     "render": "kpi" },
      "telegram":  { "show": true, "line": "host", "pos": 10,
                     "format": "RAM {value}%", "sep": " · " } }
  ]
}

Erfolgreiche Antwort:

{ "accepted": true, "effective": "green", "next_expected_by": "2026-07-12T10:26:13Z" }

7. Einbindung eines Monitor-Skripts (monitor.sh-Stil)

Wenn Sie bereits ein Cron-Integritätsprüfungsskript ausführen, fügen Sie ein Best-Effort-Skript POST hinzu Ende seines Ticks. Ein Lieferfehler darf das Häkchen nicht zerstören: Der Watchdog wird es tun Ich werde sowieso längeres Schweigen einfangen.

# monitor.env
EXTOPS_REPORT_URL="https://extops.dev/api/v1/monitoring/report"
EXTOPS_REPORT_TOKEN="<monitoring token from Settings>"

# end of the tick: build the payload with jq from the values you already computed,
# then push it best-effort (never let delivery break the tick itself)
payload="$(jq -n --arg sev "$SEVERITY" '{
  schema_version: "2.0",
  generated_at: (now | todate),
  metrics: [ { id: "overall", kind: "status", state: $sev, severity: $sev } ]
}')"
curl -sS -m 10 -X POST "$EXTOPS_REPORT_URL" \
  -H "Authorization: Bearer $EXTOPS_REPORT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$payload" || true

Ordnen Sie die Schweregrade Ihres Skripts dem kanonischen Satz zu (critical ist). akzeptiert und normalisiert auf crit) und füttern Sie Ihre bestehende Problemliste in die Metrik issues. Setzen Sie das deklarierte Intervall gleich dem Cron Zeitraum.

8. Telegram: separate Statusmeldung und Warnungen

• Überwachungsdaten gehen an Telegram als separater bearbeitbarer Status Nachricht, verschieden vom Status der benutzerdefinierten Metriken: Header + der reservierte Zeile pings + die Zeilen, die Ihr Bericht deklariert.
• Optional Routenüberwachung zu a separate Gruppe/Chat; wenn nicht gesetzt, wird der Kanal-Chat der Erweiterung verwendet. Der Bot-Transport wird mit geteilt Der Kanal der Erweiterung.
• Edge-Benachrichtigungen Feuer bei jeder Änderung der Aggregatfarbe, in beiden Anweisungen, einschließlich Wiederherstellung zurück zum grünen Zustand (mit Dauer des Vorfalls). Während die Farbe ist stabil, es herrscht Stille; Konfigurationsänderungen (Pausieren, Pings bearbeiten) nicht alarmieren.

9. Der maschinenlesbare Vertrag

Die formale Beschreibung des Berichtsendpunkts, das Nutzlastschema, die reservierten ids und die Ampelsemantik ist die Datei OpenAPI 3.1. Es trägt die gleiche Vertragsversion (2.0.0).