---
title: Santé, métriques et alertes
description: Les sondes /healthz et /readyz, les métriques internes protégées, les sept alertes, leurs canaux et la démarche de diagnostic.
---

# 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](../06-administration-et-supervision/08-page-exploitation.md). |

### Lire /readyz

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

```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`.

> [!TIP]
> Le proxy Coolify route toutes les adresses du web. Si possible, bloquez `/internal/` au proxy pour les adresses extérieures, en plus du jeton.

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

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.**

| 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](../06-administration-et-supervision/09-arret-global.md). |

4. **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](08-sauvegarde-et-restauration.md).
