Set-OPS-Public/docs/metriques-conception.md

Métriques dérivées des rôles

Pour qui : celui qui ajoute un rôle à Set-OPS et se demande comment ses mesures arrivent dans Prometheus — et celui qui exploite et veut savoir d'où sortent les courbes qu'il regarde.

La règle en une phrase. Un rôle déclare l'exportateur de ses propres mesures ; le moteur en dérive la cible de scrutation et les panneaux. Comme meta/flux.yml engendre nftables et OPNsense, comme meta/supervision.yml engendre les services Icinga.

Pourquoi un second fichier

meta/supervision.yml et meta/metriques.yml répondent à des questions différentes, sur des données différentes, pour des consommateurs différents.

	ce qu'il déclare	la question	le consommateur
supervision.yml	une sonde qui rend un verdict avec un TTL	est-ce cassé ?	Icinga
metriques.yml	un exportateur qui expose une série	depuis quand, et vers où ?	Prometheus → Grafana

Ce n'est pas une frontière inventée pour l'occasion. docs/supervision-conception.md la pose déjà dans l'autre sens :

Une métrique à seuil — durée de collecte, volume de journaux, taux d'occupation — appartient à Prometheus et Grafana. Icinga répond à une seule question : est-ce cassé ? Mélanger les deux rendrait les deux moins lisibles.

Ce document est l'autre moitié de cette phrase.

Le constat qui l'a rendu nécessaire

Mesure du 2026-09-14 : aucune métrique de service n'était collectée. Prometheus ne scrutait que les node_exporter — processeur, mémoire, disques, réseau. Rien de PostgreSQL, rien de l'annuaire, rien des boîtes, rien du cache.

Le crochet existait pourtant : serveur_prometheus_cibles_supplementaires, une liste libre, documentée, et que personne ne remplissait. Une facilité offerte à qui saurait qu'elle existe n'est pas un mécanisme ; c'est une note de bas de page.

Ce qu'un rôle déclare

# roles/<rôle>/meta/metriques.yml
exportateur:
  paquet: prometheus-postgres-exporter
  service: prometheus-postgres-exporter
  port: 9187
  job: postgresql

panneaux:
  - titre: "Taux de succès du cache"
    expr: "..."
    unite: ratio
    raison: "..."

L'exportateur est ce que le rôle installe pour qu'il y ait quelque chose à lire. Le rôle le pose lui-même : il connaît ses chemins, son compte de service, sa vérité de terrain.

Les panneaux sont ce qui mérite d'être regardé dans le temps.

Combien de panneaux : un par QUESTION QU'ON SE POSE

Ni un par métrique — un exportateur en publie couramment plus de deux cents — ni un par rôle. Un par question qu'on se pose vraiment quand quelque chose commence à aller moins bien.

Le critère : une série a sa place ici si elle précède un verdict, ou si elle n'en aura jamais.

• Les connexions précèdent un verdict : la sonde Icinga crie à 70 % et à 90 %, le graphe dit depuis quand ça monte. Une base qui passe de 20 à 60 connexions en trois semaines n'a rien cassé — elle annonce la date où elle cassera.
• Le taux de succès du cache n'aura jamais de verdict, et c'est pourquoi il compte. Quand les données dépassent shared_buffers, la base va chercher sur disque de plus en plus souvent. Rien ne casse, rien n'alerte : tout devient lent. C'est exactement la panne qu'un graphe voit et qu'une sonde ne verra jamais.

Ce qui bascule d'un coup appartient à Icinga. Ce qui dérive lentement n'a que le graphe pour se faire voir.

Ce que le moteur dérive

La cible de scrutation. Le nom du dossier du rôle est le nom du groupe ; les cibles sont donc les hôtes actifs de ce groupe. Un rôle déclaré sans hôte ne produit aucun job — Prometheus n'a pas à porter une cible qui n'existe pas, ni son journal à se remplir de refus prévisibles.

Les panneaux, pour le tableau de bord.

Les cibles écrites au plan (serveur_prometheus_cibles_supplementaires) complètent la dérivation, elles ne la remplacent pas : un équipement ou un service tiers n'a aucun rôle Set-OPS pour se déclarer.

Ce que le moteur ne dérive PAS, et c'est délibéré

Le flux. Le port de l'exportateur doit s'ouvrir depuis l'observatoire, et c'est meta/flux.yml qui le déclare — là où vivent déjà tous les flux du rôle. Deux fichiers pour un même fait finissent par diverger, et ce dépôt en a assez d'exemples.

Le compte de service : le moins de droits possible

Un exportateur lit des compteurs. Il n'a aucune raison de pouvoir lire des données.

Pour PostgreSQL, c'est le rôle pg_monitor — fourni par le moteur depuis la version 10 — qui donne accès aux vues de statistiques et à elles seules. Faire tourner un exportateur sous postgres serait donner les clés de la base pour lire des compteurs.

Le mot de passe vient de la voûte. Vide, l'exportateur n'est pas posé du tout : le rôle ne l'installe pas, ne crée pas le compte, et Prometheus ne dérive aucune cible. Dégrader, jamais deviner — et surtout jamais un mot de passe par défaut.

La chaîne de connexion ne passe pas par la ligne de commande. Un DATA_SOURCE_NAME en argument serait lisible dans ps par tout le monde sur la machine ; dans un fichier à 0600, il ne l'est que par root et le service.

Le chiffrement : ce qui est fait, ce qui ne l'est pas

client_metrique sert ses métriques en TLS, certificat synchronisé par client_pki.

Les exportateurs de service ne le font pas encore. La dette est écrite dans la raison du flux concerné, avec son remède — --web.config.file et l'abonnement au renouvellement. Elle n'est pas cachée derrière un silence.

Où en est la couverture

déclaration	rôles
meta/flux.yml	39
meta/authentification.yml	33
meta/empreinte.yml	32
meta/supervision.yml	28
meta/metriques.yml	1

Le second versant commence. Un rôle sans metriques.yml n'est pas fautif — beaucoup n'ont aucune série qui mérite un graphe. Mais un service qui porte de l'état et n'en déclare aucune mérite qu'on se demande pourquoi.

Quand relire ce document

• un rôle qui se met à porter de l'état → il lui faut probablement un exportateur
• un exportateur qui passe en TLS → la dette du flux se referme, et cette page le dit
• un panneau qu'on regarde sans jamais agir dessus → il n'avait pas sa place ici