Dépanner les erreurs de monitoring : méthode, commandes et pièges
Une alerte qui ne part pas n'est presque jamais un problème d'Alertmanager. La séquence de diagnostic, commande par commande.
Ton Grafana affiche un trou, l'alerte n'est jamais partie, et le service est peut-être en train de tomber. Dans neuf cas sur dix, le problème n'est pas là où le tableau de bord pointe du doigt.
On va descendre la pile couche par couche, avec les commandes exactes et les erreurs que je rencontre le plus souvent en prod. À la fin, tu auras une séquence de sept vérifications à coller dans ton runbook.
Le premier réflexe : séparer panne de collecte et panne de service
Trois situations différentes produisent le même écran vide, et elles n'ont rien à voir entre elles. Confondre les trois te fait perdre une heure à redémarrer des exporters alors que la règle d'alerte était fausse.
| Symptôme | Première commande | Cause probable |
|---|---|---|
Le service est down, la métrique up vaut 0 | up{job="api"} | Vrai incident : cible injoignable |
La métrique up n'existe pas du tout | count(up) | Prometheus ne scrape pas, ou service discovery cassé |
up vaut 1 mais les données métier manquent | count(http_requests_total) | Relabeling, nom de métrique changé, exporter muet |
| La métrique existe, aucune alerte n'est partie | ALERTS{alertstate="firing"} | Règle non chargée, routage Alertmanager, silence actif |
Exemple concret : sur une API Go, up restait à 1 pendant deux heures alors que les requêtes étaient bloquées. L'exporter répondait sur /metrics, mais la métrique http_requests_total avait été renommée lors d'une migration de client. Personne ne l'avait vue, parce que le dashboard interrogeait un nom fixe et affichait simplement « No data ».
Étape 1 — vérifier que la cible est réellement scrapée
Avant de toucher à une seule règle d'alerte, valide la configuration Prometheus. Une virgule mal placée dans un fichier YAML suffit à faire ignorer un job entier, souvent sans bruit.
promtool check config /etc/prometheus/prometheus.yml
curl -s localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, instance: .labels.instance, health, lastError}'Le champ lastError est celui que personne ne lit. Il contient fréquemment context deadline exceeded, ce qui veut dire que la cible met plus longtemps à répondre que le scrape_timeout.
Regarde aussi le nombre de séries ramenées par la cible : un exporter qui répond avec 200 mais zéro métrique exploitable est un cas classique de version incompatible.
Le piège du relabeling qui renomme le job
Beaucoup de configurations réécrivent les labels pour rendre les dashboards lisibles. La conséquence, c'est que l'alerte qui cible job="api" ne matche plus rien.
relabel_configs:
- source_labels: [__meta_kubernetes_pod_label_app]
target_label: job # 'api' devient 'api-7d9f8'
regex: (.+)-.*
replacement: $1Après ce genre de règle, teste toujours l'expression finale dans le Prometheus UI, pas dans Grafana. Grafana ajoute souvent des variables de template qui masquent le problème.
Étape 2 — vérifier que la règle d'alerte existe vraiment
Une règle syntaxiquement valide peut ne jamais s'évaluer. Le cas le plus fréquent : le fichier de règles n'est pas listé dans rule_files, ou il a été ajouté dans un volume non monté.
promtool check rules /etc/prometheus/rules/*.yml
# quelles alertes sont en cours d'évaluation, tous états confondus
count by (alertname, alertstate) (ALERTS)Si ALERTS est vide alors que tu attends une alerte, la question n'est plus « pourquoi le mail n'arrive pas » mais « pourquoi l'expression ne renvoie rien ». Teste-la directement dans l'onglet Graph de Prometheus.
groups:
- name: api
rules:
- alert: ApiErrorRateHigh
expr: |
sum(rate(http_requests_total{job="api",code=~"5.."}[5m]))
/
sum(rate(http_requests_total{job="api"}[5m])) > 0.05
for: 10m
labels:
severity: pageLe piège ici, c'est le for: 10m. Une alerte avec un for long qui repasse en dessous du seuil toutes les neuf minutes ne passe jamais en firing. Elle reste éternellement en pending, et personne ne consulte cet état.
Étape 3 — suivre le chemin jusqu'à Alertmanager
Prometheus déclenche, Alertmanager décide à qui parler. Entre les deux, il y a une configuration de routage qui absorbe silencieusement une bonne partie des alertes.
amtool check-config /etc/alertmanager/alertmanager.yml
amtool alert query --alertmanager.url=http://localhost:9093
amtool silence query --alertmanager.url=http://localhost:9093Trois suspects reviennent sans cesse : une route sans receiver correspondant, un silence oublié depuis trois semaines, et une inhibition qui masque une alerte par une autre.
Le quatrième suspect est temporel. Une alerte qui se déclenche toutes les deux minutes avec un repeat_interval: 4h ne t'enverra qu'un seul message toutes les quatre heures. Tu crois que la notification est cassée, alors que la mécanique fonctionne exactement comme configuré.
Le dead man's switch qui évite l'angle mort
La panne la plus grave n'est pas l'alerte qui hurle, c'est le pipeline entier qui se tait. Ajoute une alerte permanente qui prouve que la chaîne complète fonctionne.
- alert: Watchdog
expr: vector(1)
labels:
severity: none
annotations:
summary: "Le pipeline d'alerte est vivant"Route-la vers un canal que tu consultes tous les jours. Si ce message cesse d'arriver, tu as un problème d'infrastructure d'alerting, pas un problème de service. Ce sujet rejoint les architectures décrites dans les alternatives au monitoring classique, où l'on surveille les signaux plutôt que les machines.
Étape 4 — comprendre les trous dans les graphes
Un graphe qui descend à zéro n'indique pas forcément une chute de trafic. Souvent, il manque simplement des points, et le calcul de débit transforme ce vide en valeur aberrante.
rate() a besoin d'au moins deux échantillons dans la fenêtre. Avec un scrape de 30 secondes, une fenêtre [1m] ne contient que deux points : la moindre requête lente casse le calcul.
# fragile : fenêtre trop courte pour un scrape de 30 s
rate(http_requests_total[1m])
# robuste : au moins 4 points, tolère un scrape manqué
rate(http_requests_total[5m])Autre source de faux trous : la staleness. Quand une cible disparaît, Prometheus marque ses séries comme obsolètes au bout de cinq minutes. Pendant ce temps, les agrégations continuent de renvoyer les dernières valeurs connues, ce qui donne l'illusion d'un service vivant.
Pour un tableau de bord de capacité, travaille plutôt avec avg_over_time() sur une fenêtre longue. Tu lisses les micro-trous sans masquer une vraie coupure.
Étape 5 — traquer la cardinalité avant qu'elle ne te coûte la facture
Une seule étiquette mal choisie peut multiplier le nombre de séries par cent. Le symptôme est progressif : Prometheus ralentit, les requêtes expirent, puis l'écriture disque sature.
topk(10, count by (__name__) ({__name__=~".+"}))
count by (job) ({__name__=~".+"})
curl -s localhost:9090/api/v1/status/tsdb | jq '.data.seriesCountByMetricName[:5]'Le coupable habituel, c'est un label user_id, request_id ou une URL avec paramètres. Ces valeurs doivent vivre dans les logs ou les traces, jamais dans une métrique.
| Étiquette | Séries typiques | Verdict |
|---|---|---|
code="500" | 5 | Sain |
route="/api/users/:id" | 30 | Sain si normalisé |
route="/api/users/12345" | 100 000+ | Fuite de cardinalité |
user_id | illimité | À supprimer des métriques |
Corrige côté instrumentation, pas côté Prometheus. Un metric_relabel_configs qui jette l'étiquette coupe l'hémorragie, mais tu perds la granularité pour toujours.
Étape 6 — alerter sur un budget d'erreur, pas sur un seuil arbitraire
Les seuils fixes produisent deux pathologies symétriques : des alertes qui se déclenchent pour rien, et des incidents majeurs qui passent sous le radar parce que 2 % d'erreurs, c'était « acceptable ».
Le principe du burn rate compare la vitesse de consommation du budget d'erreur à la cible SLO. Sur un objectif de 99,9 % par mois, tu as environ 43 minutes d'indisponibilité autorisées.
# consommation 14,4x trop rapide : le budget part en 2 jours
(
sum(rate(http_requests_total{job="api",code=~"5.."}[1h]))
/
sum(rate(http_requests_total{job="api"}[1h]))
) / (1 - 0.999) > 14.4Cette approche est détaillée dans le chapitre monitoring du SRE Book de Google, et elle change vraiment la charge mentale d'astreinte. Une alerte devient une décision économique, pas un réflexe.
Pour la partie collecte, les spécifications OpenTelemetry sur les métriques décrivent les instruments à privilégier : compteurs, histogrammes, jauges. Choisir le bon instrument évite la moitié des erreurs de calcul décrites plus haut.
Le runbook de dépannage en sept commandes
Quand une alerte manque, applique cette séquence dans l'ordre. Elle élimine les causes par probabilité décroissante, sans redémarrer quoi que ce soit.
# 1. La cible répond-elle ?
curl -s localhost:9090/api/v1/targets | jq '.data.activeTargets[] | select(.health!="up")'
# 2. La règle est-elle valide et chargée ?
promtool check rules /etc/prometheus/rules/*.yml
curl -s localhost:9090/api/v1/rules | jq '.data.groups[].rules[] | select(.health!="ok")'
# 3. L'expression renvoie-t-elle quelque chose ?
# (copier-coller l'expr de la règle dans l'onglet Graph)
# 4. L'alerte est-elle en firing côté Prometheus ?
curl -s localhost:9090/api/v1/alerts | jq '.data.alerts[] | {name, state, activeAt}'
# 5. Alertmanager la voit-il ?
amtool alert query --alertmanager.url=http://localhost:9093
# 6. Un silence ou une inhibition la masque-t-il ?
amtool silence query --alertmanager.url=http://localhost:9093
# 7. La notification sort-elle du cluster ?
curl -s -X POST localhost:9093/api/v2/alerts -H 'Content-Type: application/json' \
-d '[{"labels":{"alertname":"TestManuel","severity":"page"}}]'Le test manuel de l'étape 7 est celui qui tranche le plus vite. S'il produit une notification, le problème est en amont, dans les règles. S'il ne produit rien, il est en aval, dans le routage ou le receiver.
Garde aussi une trace des outils que tu utilises au quotidien : la comparaison entre Prometheus et les autres solutions open source de supervision explique pourquoi les mêmes erreurs ne se corrigent pas de la même façon partout.
FAQ
Pourquoi mon alerte passe en pending et n'en sort jamais ?
Le champ for est plus long que la durée réelle du pic. Vérifie la valeur de ALERTS_FOR_STATE et raccourcis le for, ou augmente la fenêtre de ton rate() pour lisser la mesure.
Prometheus dit « context deadline exceeded » sur une cible saine
La collecte dépasse le scrape_timeout. Monte-le à 15 secondes maximum, ou réduis le nombre de métriques exposées. Un exporter qui met vingt secondes à répondre n'a pas un problème réseau, il a un problème de conception.
Comment retrouver une alerte qui a disparu après un redéploiement ?
Compare le hash du fichier de règles avec celui du dernier commit, puis vérifie que le volume est bien monté. Les règles sont rechargées par POST /-/reload ou par un SIGHUP ; un conteneur qui n'a pas reçu le signal garde l'ancienne version en mémoire.
Faut-il alerter sur chaque métrique qui bouge ?
Non. Une alerte doit exiger une action. Si la réponse attendue est « regarder le graphe », ce n'est pas une alerte, c'est un dashboard.