Déploiement et exploitation

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#

RouteAccèsContenu
GET /healthzPublic{"ok":true} : le processus web répond. Rien d'autre.
GET /readyzPublic200 si les capacités database, identity et queue sont prêtes, sinon 503 avec la liste unavailable.
GET /internal/metricsJeton porteur MVP_METRICS_TOKENJauges au format Prometheus, sans nom ni identifiant de projet.
/operationsAdministrateur, en sessionPage Exploitation, voir Page Exploitation.

Lire /readyz#

bash
curl -sS https://maintenance.maintain.example/readyz
Capacité indisponibleCause probable
databaseBase injoignable, non migrée, ou rôle runtime pas assez restreint.
identityIdentité désactivée, configuration des codes ou de la messagerie incomplète, ou battement du worker de messagerie absent.
queueRedis injoignable ou non configuré.

Interroger les métriques#

bash
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#

AlerteCodeGravitéCauses
Messagerie indisponiblemail_unavailableCritiqueTransport absent ou invalide, échecs, worker de messagerie silencieux depuis plus de 120 s, file en retard
File de travail bloquéequeue_stalledCritiqueRedis injoignable, travaux en retard, bloqués depuis 15 min ou abandonnés après 5 tentatives
Journal d'audit indisponibleaudit_unavailableCritiqueFile de secours non vide ou illisible, rôle runtime non restreint, échec d'écriture
Disque ou base saturésstorage_saturatedCritiqueEspace libre sous le seuil, base au-delà de 90 % du seuil, connexions au-delà de 90 %, base injoignable
Consommation IA inconnueusage_unknownAttentionAppel au modèle sans compteur confirmé sur 24 h
Publication au résultat incertainpublication_ambiguousAttentionÉcriture GitHub ou notification sans confirmation
Fournisseur indisponibleprovider_unavailableAttentionÉ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#

  1. Journal technique, toujours actif : événements alert_opened, alert_continuing, alert_reopened, alert_resolved.
  2. Page Exploitation, pour l'Administrateur.
  3. 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#

  1. Constater. Ouvrez /operations ou interrogez /internal/metrics. Relevez les alertes ouvertes et leur première détection.
  2. Corréler. Filtrez les journaux du web et du worker sur event (alert_opened, provider_call, job_failed), puis sur le correlationId.
  3. Agir selon l'alerte.
AlerteVérifierAgir
mail_unavailableVariables de messagerie, journal provider_call du fournisseur mail, /readyzCorrigez la configuration ou attendez le fournisseur. Les personnes redemandent un code.
queue_stalledSanté 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_unavailableFile de secours du stockage privé, droits du rôle runtimeRéconciliez avant de vider la file de secours.
storage_saturatedEspace du volume platform-storage, taille de la base, connexionsLibérez de l'espace, lancez la rétention, agrandissez le volume.
usage_unknownPage de l'exécution, page ConsommationRéconciliez avec la facture du fournisseur.
publication_ambiguousDétail de l'exécution, branche et PR sur GitHubRéconciliez à la main. Rien n'est rejoué automatiquement.
provider_unavailableJournal provider_call, état du fournisseurAttendez ou corrigez les droits. Si les effets doivent cesser, activez l'arrêt global.
  1. Clore. Vérifiez la ligne alert_resolved dans 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.