Maison/Documents/Surveillance

Contrat de surveillance

Version du contrat 2.0.0 · Charge utile schema_version 2.0 · Plans d'essai/payants

La surveillance met votre poste sous surveillance constante : un feu tricolore allumé en direct sa carte dans la liste, une base surveillance onglet dans Détails et message d'état Telegram distinct avec alertes de périphérie. Il combine deux composants activés indépendamment : un pousser le rythme cardiaque (un agent sur l'hôte de votre service se présente selon un horaire déclaré ; le silence est de mise lui-même un signal) et pings de disponibilité (le panneau vérifie votre URLs publics pour la disponibilité).

1. Comment ça marche (deux composants, une lumière)

• Pousser le rythme cardiaque: un script cron sur votre hôte (par exemple un script adapté monitor.sh) POSTs un rapport de métriques v2 au panneau à l'intervalle tu as déclaré. Chaque rapport doit porter le verdict réservé overall. Les rapports manqués font monter la lumière (interrupteur homme mort) : si l'hôte, le réseau ou cron meurt, vous le voyez précisément parce que les appels s'arrêtent.
• Pings de disponibilité: le panel lui-même demande périodiquement au public URLs que vous configurez (site, api, docs) et vérifie uniquement la disponibilité, jamais la contenu. Aucun agent n'est nécessaire, un URL suffit.

Une extension est "en surveillance" lorsque la surveillance est activée et qu'au moins un Le composant est configuré. Sinon sa carte présente un point gris neutre.

1b. Heartbeats et le pool de machines à sous

La surveillance se déroule au niveau de l'extension sous la forme de deux listes plates indépendantes qui partagent un pool d'emplacements : pulsations cardiaques (producteurs poussés, anciennement « stands ») et pings de disponibilité (tirer des chèques). Une extension peut avoir plusieurs battements de cœur – par exemple un hôte principal et un travailleur rémunéré. Chaque battement de coeur pousse rapporte avec son propre jeton au porteur et déclare le sien présentation (onglets, sections et lignes Telegram) via son label. Les pings de disponibilité sont une liste plate distincte appartenant à l'extension, non imbriquée sous aucun battement de coeur. Le panneau fusionne tout en une seule lumière globale (la pire), une Surface détaillée et un message récapitulatif Telegram.

Les battements de cœur et les pings partagent un seul par extension pool de machines à sous: un un battement de coeur coûte un emplacement, un ping actif coûte un emplacement, et leur somme ne doit pas dépasser le max_slots du plan (Essai 3 · Studio 10 · Flotte 25). Le dépassement du pool renvoie 409 slot_limit ; après un déclassement, l'excédent est suspendu (pings en premier, battements de cœur en dernier). La réponse porte slots_used et max_slots pour que l'interface utilisateur puisse afficher le budget.

2. Le feu tricolore

L'agrégat est le le pire des cumul sur chaque activé composant du battement de coeur et la lumière de chaque ping actif, où les sévérités sont classées comme ok < warn < crit. La composante d'un battement de coeur est max(reported, watchdog) : reported est la gravité du overall métrique de la dernière accepté rapport; watchdog est un plancher de fraîcheur calculé à partir de la propre réception du panneau horloge (le décalage de l’horloge de l’agent est inoffensif).

La gravité est canonique ok | warn | crit. Les alias conviviaux sont normalisés lors de l'admission : warning devient warn ; error et critical deviennent crit.

3. Chien de garde (battements cardiaques manqués)

Vous déclarez l'intervalle de rapport attendu (60 s à 24 h) lors de l'activation du battement de coeur. Le chien de garde étage ensuite la lumière par fraîcheur, avec grace = max(60s, 25% of the interval) pour absorber la gigue cron et réseau :

Un rapport rejeté (401/422/429) n'actualise jamais le chien de garde, donc un rapport cassé l'agent escalade honnêtement ; le dernier motif de refus est visible dans le paramètres de surveillance. La récupération est instantanée : le premier rapport accepté recalcule la lumière immédiatement.

4. Pings de disponibilité

Un ping est une vérification de disponibilité nommée d'un https URL public. Le panneau effectue GET avec un délai d'attente de 10 s, suit au plus 5 redirections, ne lit aucun corps au-delà d'une limite minimale et traite un statut final de la classe 2xx comme succès (204 et 206 comptent aussi). Une finale 3xx (boucle ou limite de redirection), 4xx, 5xx, délai d'attente ou erreur DNS/TLS/réseau est un échec. Une vérification échouée est confirmée par une nouvelle tentative après environ 15 s avant qu'elle ne compte, qui absorbe les incidents de réseau uniques.

Les résultats du ping apparaissent sous forme de métriques propriétaires ping:<name> dans le pings section (Uptime) de la base surveillance onglet et comme ligne réservée Telegram pings : 🟢 api 210ms · 🟢 site 90ms · 🔴 docs (timeout). Le nombre de pings par extension et l'intervalle minimum dépendent du forfait :

La surveillance dans son ensemble est une version d'essai/payante uniquement ; l'intervalle minimum de battement de coeur est de 60 secondes sur tous les forfaits.

5. Mettre une extension en surveillance

Dans les extensions Paramètres, bloc de surveillance :

• Activez la surveillance (forfaits d'essai/payants).
• Pulsation: activez-le et déclarez l'intervalle de rapport ; le panneau délivre un porteur jeton de surveillance, affiché exactement une fois (faites-le pivoter à tout moment ; l'ancien jeton obtient immédiatement 401). Mettez le jeton et le point de terminaison URL dans l'environnement de votre agent.
• Pings : ajoutez des URL publics nommés (par exemple site, api, docs) avec un intervalle par ping, jusqu'à la limite du plan.
• Telegram : activez la surveillance de la livraison et définissez éventuellement un groupe/chat séparé.

6. Le format du rapport

Le rapport contient la même charge utile v2 basée sur les métadonnées que le contrat de métriques personnalisées (onglets, sections, Telegram lignes, métriques), poussé vers POST /api/v1/monitoring/report avec Authorization: Bearer <monitoring token>. La surveillance ajoute identifiants réservés :

Limites : charge utile au maximum 64 Ko, tout au plus 200 métriques, au plus 2 rapports par minute par source (l'excédent obtient 429 et ne ne compte pas comme un battement de coeur).

6.1. Exemple de rapport

{
  "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": " · " } }
  ]
}

Réponse réussie :

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

7. Intégration d'un script de moniteur (style moniteur.sh)

Si vous exécutez déjà un script de vérification de l'état cron, ajoutez un POST de notre mieux au niveau du fin de sa tique. Un échec de livraison ne doit pas briser le tic-tac : le chien de garde attrapez quand même un silence prolongé.

# 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

Mappez les gravités de votre script sur l'ensemble canonique (critical est accepté et normalisé à crit) et alimentez votre liste de problèmes existante dans la métrique issues. Définissez l'intervalle déclaré égal au cron période.

8. Telegram : message d'état et alertes séparés

• Les données de surveillance vont à Telegram en tant que statut modifiable séparé message, distinct du statut des métriques personnalisées : en-tête + le ligne pings réservée + les lignes déclarées par votre rapport.
• En option, acheminez la surveillance vers un groupe/chat séparé; quand pas défini, le canal de discussion de l'extension est utilisé. Le transport du bot est partagé avec le canal du poste.
• Alertes de périphérie feu à chaque changement de couleur globale, dans les deux directions, y compris le retour au vert (avec la durée de l'incident). Tandis que la couleur est stable il y a le silence ; modifications de la configuration (pause, modification des pings) ne pas alerter.

9. Le contrat lisible par machine

La description formelle du point de terminaison du rapport, le schéma de charge utile, le Les identifiants et la sémantique des feux de signalisation sont le fichier OpenAPI 3.1. Il porte le même version du contrat (2.0.0).