Santé, métriques et alertes
L'instance expose deux sondes publiques, des métriques protégées par jeton et une page d'exploitation. Le worker évalue sept alertes en continu. Cette page explique comment les lire et comment diagnostiquer.
Qui peut le faire : l'exploitant pour les sondes, les métriques et les journaux ; l'Administrateur pour la page Exploitation.
Points d'accès#
| Route | Accès | Contenu |
|---|---|---|
GET /healthz | Public | {"ok":true} : le processus web répond. Rien d'autre. |
GET /readyz | Public | 200 si les capacités database, identity et queue sont prêtes, sinon 503 avec la liste unavailable. |
GET /internal/metrics | Jeton porteur MVP_METRICS_TOKEN | Jauges au format Prometheus, sans nom ni identifiant de projet. |
/operations | Administrateur, en session | Page Exploitation, voir Page Exploitation. |
Lire /readyz#
curl -sS https://maintenance.maintain.example/readyz| Capacité indisponible | Cause probable |
|---|---|
database | Base injoignable, non migrée, ou rôle runtime pas assez restreint. |
identity | Identité désactivée, configuration des codes ou de la messagerie incomplète, ou battement du worker de messagerie absent. |
queue | Redis injoignable ou non configuré. |
Interroger les métriques#
curl -sS https://maintenance.maintain.example/internal/metrics \
-H "Authorization: Bearer $MVP_METRICS_TOKEN"Sans MVP_METRICS_TOKEN, la route répond 404. Avec un mauvais jeton, 401. Le jeton n'est jamais accepté dans l'adresse. Une valeur non mesurable est omise, jamais remplacée par zéro.
Exemples de jauges : maintain_queue_pending, maintain_queue_overdue, maintain_mail_failing, maintain_usage_unknown_24h, maintain_publication_unknown, maintain_disk_free_ratio, maintain_database_bytes, maintain_alert_open.
Les sept alertes#
| Alerte | Code | Gravité | Causes |
|---|---|---|---|
| Messagerie indisponible | mail_unavailable | Critique | Transport absent ou invalide, échecs, worker de messagerie silencieux depuis plus de 120 s, file en retard |
| File de travail bloquée | queue_stalled | Critique | Redis injoignable, travaux en retard, bloqués depuis 15 min ou abandonnés après 5 tentatives |
| Journal d'audit indisponible | audit_unavailable | Critique | File de secours non vide ou illisible, rôle runtime non restreint, échec d'écriture |
| Disque ou base saturés | storage_saturated | Critique | Espace libre sous le seuil, base au-delà de 90 % du seuil, connexions au-delà de 90 %, base injoignable |
| Consommation IA inconnue | usage_unknown | Attention | Appel au modèle sans compteur confirmé sur 24 h |
| Publication au résultat incertain | publication_ambiguous | Attention | Écriture GitHub ou notification sans confirmation |
| Fournisseur indisponible | provider_unavailable | Attention | Échecs consécutifs avec GitHub, Langdock, le scanner ou le webhook de notification |
Un appel fournisseur compte comme échec pour un statut 401, 403, 429, 5xx ou une erreur réseau.
Cycle d'une alerte#
- Elle est notifiée à son ouverture.
- Tant qu'elle persiste, un rappel part au plus une fois par
MVP_ALERT_REPEAT_MINUTES(240 minutes par défaut). - Une alerte qui retombe puis revient dans cette fenêtre rouvre la même ligne, sans nouvelle notification.
- Sa résolution est notifiée une fois. Elle se résout seule au cycle qui suit le retour à la normale.
- Les alertes résolues sont purgées après
MVP_ALERT_RETENTION_DAYS(90 jours par défaut).
Canaux#
- Journal technique, toujours actif : événements
alert_opened,alert_continuing,alert_reopened,alert_resolved. - Page Exploitation, pour l'Administrateur.
- E-mail, si
MVP_ALERT_MAIL_ENABLED=true: envoyé par la messagerie de l'instance aux Administrateurs actifs (20 au plus). Le message ne contient que le type, la cause, la date et le lien vers/operations.
L'arrêt global ne suspend pas la surveillance.
Journaux techniques#
Le web et le worker écrivent une ligne JSON par événement sur la sortie standard, avec un champ event. Les valeurs sensibles sont omises : mots de passe, jetons, codes, adresses, contenus. Une erreur n'est journalisée que par son nom.
Chaque requête reçoit un identifiant de corrélation, renvoyé dans l'en-tête X-Correlation-Id et repris dans le champ correlationId des journaux. Le journal des actions retrouve la même demande avec le filtre Corrélation.
Diagnostiquer#
- Constater. Ouvrez
/operationsou interrogez/internal/metrics. Relevez les alertes ouvertes et leur première détection. - Corréler. Filtrez les journaux du web et du worker sur
event(alert_opened,provider_call,job_failed), puis sur lecorrelationId. - Agir selon l'alerte.
| Alerte | Vérifier | Agir |
|---|---|---|
mail_unavailable | Variables de messagerie, journal provider_call du fournisseur mail, /readyz | Corrigez la configuration ou attendez le fournisseur. Les personnes redemandent un code. |
queue_stalled | Santé de Redis et du worker (worker.js --health), jauges maintain_queue_* | Redémarrez Redis ou le worker. Ne supprimez jamais un travail au résultat inconnu. |
audit_unavailable | File de secours du stockage privé, droits du rôle runtime | Réconciliez avant de vider la file de secours. |
storage_saturated | Espace du volume platform-storage, taille de la base, connexions | Libérez de l'espace, lancez la rétention, agrandissez le volume. |
usage_unknown | Page de l'exécution, page Consommation | Réconciliez avec la facture du fournisseur. |
publication_ambiguous | Détail de l'exécution, branche et PR sur GitHub | Réconciliez à la main. Rien n'est rejoué automatiquement. |
provider_unavailable | Journal provider_call, état du fournisseur | Attendez ou corrigez les droits. Si les effets doivent cesser, activez l'arrêt global. |
- Clore. Vérifiez la ligne
alert_resolveddans le journal.
Limite connue#
Aucune sonde externe n'est fournie. Si l'hôte ou le worker s'arrête, la surveillance interne s'arrête avec lui. Vérifiez régulièrement l'état des conteneurs dans Coolify. Vous pouvez ajouter votre propre sonde sur /healthz.
Pour continuer#
Protégez vos données avec Sauvegarde et restauration.