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

```yaml
# 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 et ne crée pas le compte — jamais un mot de passe par défaut. **Prometheus,
lui, dérive quand même la cible** (`:9187`) de tout hôte de `serveur_postgresql` : sans le
secret, la collecte d'`obs-01` passe au rouge. C'est voulu — une base sans métriques doit se
voir, et renseigner le secret est la façon de l'éteindre. *(Cette page promettait l'inverse
jusqu'au 2026-09-28.)*

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