Les alertes Prometheus

Carte de maintenance du code d’alerte : où se trouve quoi, et comment l’étendre sans rien casser. Le fonctionnement côté administrateur est décrit dans Monitoring & Alertes.

Logique pure vs câblage

Le code est scindé en deux, pour garder la génération des règles testable :

• dnf/lib/alerts.nix : fonctions pures qui produisent les règles Prometheus à partir de la topologie. Testées dans dnf/tests/unit/lib/alerts_test.nix.
• dnf/modules/service/prometheus.nix : câblage impur (Alertmanager, routage par sévérité, sops, bot Matrix, vhost, sondes blackbox).

Toute logique non triviale va dans alerts.nix ; le module se contente de la brancher.

Les helpers (alerts.nix)

Exposés via dnfLib (voir dnf/lib/default.nix) :

Helper	Rôle
serviceUnits	Service DNF → unité systemd (ex. idm → kanidm.service)
nodeClass	Classe d’un nœud (critique / non-critique / désactivé) : features alert-* puis profil
nodeAlertEligible	Sélection : un nœud n’est surveillé que s’il est nœud réseau/serveur, porte alert-non-critical, ou héberge un service mappé
severityForClass	Classe → sévérité (critical ou warning)
hostExpectedUnits	Unités attendues d’un hôte (d’après ses services activés)
mkNodeRuleGroups	NodeDown, ServiceDown, SystemdUnitFailed (+ label reach local/wan)
mkResourceRuleGroups	Disque, RAM, charge, inodes, OOM, FS read-only, prédiction disque, horloge, conntrack
mkNetworkRuleGroups	Sondes blackbox (passerelle, tailnet, DNS, ZoneInternetDown)
mkHttpRuleGroups	Sondes HTTP : ServiceEndpointDown + expiration de certificat TLS
mkResticRuleGroups	Fraîcheur des sauvegardes (ResticBackupStale/Critical)
mkSmartctlRuleGroups	Santé disque SMART (DiskSmartFailing, DiskTemperatureHigh)
mkPostfixRuleGroups	Relais Postfix (PostfixRelayUnhealthy, PostfixDeferredQueueHigh)
mkSynapseRuleGroups	Synapse (SynapseRestarting, SynapseHighErrorRate)
mkMaintenanceRuleGroups	Drapeau de maintenance (silence pendant rebuild)
mkTailscaleRuleGroups	Auto-réparation tailnet (TailscaleUnhealthy, TailscaleFlapping)
mergeRuleGroups	Fusionne des fragments en un seul document
mkAlertRuleGroups	Raccourci : nœuds + ressources + restic + SMART + tailscale
mkSilenceRoutes	Routes Alertmanager vers le receiver null (alertes connues, acceptées)

Le label host, ou pourquoi les alertes se nomment

Chaque cible de scrape porte un label host valant le nom d’hôte, posé par mkHostTargets dans prometheus.nix (un static_config par hôte plutôt qu’une liste unique de cibles). Deux effets :

• le bot Matrix affiche DiskSpaceLow at srv-backup au lieu de l’instance brute <ip>:<port> ;
• une route de silence peut viser une seule machine.

Le poser au scrape le propage gratuitement à toutes les alertes issues de ces jobs, y compris les règles ressources génériques, qui ignorent tout de la topologie à l’évaluation.

Les agrégations effacent les labels

Une clause by (...) supprime tout label non groupé. ResticBackupStale (max by (instance, job, host)) et SynapseHighErrorRate (sum by (instance, host)) citent donc host explicitement. L’oublier dans une nouvelle règle agrégée fait retomber la notification sur l’instance brute.

Le bot n’affiche pas summary

Le bot Matrix rend le titre puis l’annotation description, et ne se rabat sur summary que si description est absente : toutes les règles DNF en définissent une, donc summary ne lui parvient jamais. Une information à faire figurer dans la notification doit aller dans description.

Sélection des nœuds surveillés

La supervision est opt-out pour l’infrastructure, opt-in pour le reste. nodeAlertEligible retient un nœud uniquement s’il est de classe critical (profil gateway/hcs/server ou feature alert-critical), s’il porte explicitement alert-non-critical, ou s’il héberge au moins un service mappé dans serviceUnits. Un laptop/desktop nu ne génère donc aucune alerte node.

Panne internet vs hôte distant down

Le Prometheus d’une zone joint les hôtes des autres zones (ex. le HCS public) uniquement via le WAN. Quand internet tombe, ces cibles deviennent injoignables et déclencheraient un faux « host down ». Pour l’éviter :

• chaque règle node porte un label reach (local même zone, wan cross-zone) ;
• une sonde blackbox ICMP vers des IP externes alimente ZoneInternetDown (déclenchée seulement si toutes les cibles externes échouent) ;
• une règle d’inhibition Alertmanager (equal: [zone]) fait taire les alertes reach="wan" de la zone tant que ZoneInternetDown est active — la vraie cause est notifiée, pas les symptômes.

Le piège : un seul document de règles

À ne jamais oublier

NixOS concatène toutes les entrées de services.prometheus.rules (une liste de chaînes) dans un seul fichier. Plusieurs documents groups: sans séparateur --- → seul le premier est lu. Empiler une deuxième entrée casse silencieusement les groupes suivants.

On fusionne donc tout via mergeRuleGroups, puis on n’émet qu’une entrée :

dnf/modules/service/prometheus.nix

services.prometheus.rules = [
  (builtins.toJSON (dnfLib.mergeRuleGroups (
    [ (dnfLib.mkAlertRuleGroups { inherit nodes; /* … */ }) ]
    ++ lib.optional alerting.silenceOnRebuild (dnfLib.mkMaintenanceRuleGroups { /* … */ })
    ++ lib.optional alerting.network.enable (dnfLib.mkNetworkRuleGroups { /* … */ })
  )))
];

Où ajouter quoi

Je veux…	Je touche…
surveiller un nouveau service	serviceUnits dans alerts.nix
une nouvelle famille de règles	un mkXRuleGroups + l’ajouter au mergeRuleGroups du module
câbler un exporter de métriques	exporter dans son module (gated monitoring-node, bind preferredIp) + job de scrape + mkXRuleGroups gated dans prometheus.nix
changer un seuil par défaut	defaultThresholds dans alerts.nix
changer la classe d’un nœud	feature alert-*[:zone] (aucun code)
forcer/exclure un nœud de la surveillance	feature alert-non-critical / alert-disabled
surveiller une URL + son certificat TLS	alerting.network.httpProbeUrls dans la config
ajuster la détection de panne internet	alerting.network.internetProbeTargets
taire une alerte connue et acceptée	alerting.silences dans un module consumer (aucun code)
taire une unité systemd cassée sur tout le parc	ignoredUnits dans dnf/config/alerts.nix
une nouvelle destination	le bloc alertmanager de prometheus.nix (receiver + route)

Convention DNF

Un helper de lib/ = un test. Toute fonction ajoutée à alerts.nix se double d’un cas dans dnf/tests/unit/lib/alerts_test.nix (nix-unit).

Ordre des routes Alertmanager

continue vaut false par défaut : la première route enfant qui matche gagne. Les routes de mkSilenceRoutes doivent donc être insérées avant les routes par sévérité, sinon elles ne sont jamais atteintes et l’alerte notifie quand même. Le receiver null est partagé avec la route de maintenance, d’où sa garde silenceOnRebuild || silences != [] : référencer un receiver absent empêche Alertmanager de démarrer.

Métrique textfile : permissions

Un fichier .prom du collecteur textfile doit être lisible par node-exporter (utilisateur non-root). mktemp crée en 0600 : poser un chmod 0644 avant le mv atomique, sinon le fichier est ignoré (node_textfile_scrape_error 1) et la métrique n’est jamais exposée, donc l’alerte reste aveugle.