Nommage des métriques et cardinalité des labels : les unités dans le nom, des valeurs bornées dans les labels

Ce que c'est

Le nom d'une métrique indique ce qui est mesuré ; les labels indiquent pour quelle tranche. Le guide de nommage de Prometheus fixe les conventions : un préfixe d'application ou de sous-système en un seul mot (http_, process_), une unité et une grandeur par métrique, des unités de base (secondes, octets, pas millisecondes ni mégaoctets), l'unité en suffixe au pluriel, _total pour les comptes cumulatifs et _info pour les pseudo-métriques de métadonnées. Exemples tirés du guide : http_request_duration_seconds, process_cpu_seconds_total, http_requests_total. Le guide énonce aussi un test : le sum() ou la avg() sur toutes les dimensions de labels d'une même métrique doit avoir un sens ; si ce n'est pas le cas, les données relèvent de deux métriques distinctes. Il note que d'autres conventions, dont celle d'OpenTelemetry, laissent l'unité hors du nom et la placent dans les métadonnées ; Prometheus recommande de la garder dans le nom afin que la configuration des alertes et des tableaux de bord reste lisible sans schéma.

Les labels sont les dimensions : operation="create", stage="extract", un code de statut, un gabarit de route. La mise en garde du guide en est la moitié importante : chaque combinaison unique de valeurs de labels crée une nouvelle série temporelle, si bien que les labels ne doivent pas porter d'ensembles non bornés tels que des identifiants utilisateur ou des adresses e-mail.

Pourquoi c'est important

Une série coûte de la mémoire, du CPU, du disque et du réseau aussi longtemps qu'elle existe. Le guide d'instrumentation donne des ordres de grandeur : garder la cardinalité d'une métrique sous 10 à titre indicatif, considérer tout ce qui dépasse 100, ou qui risque de croître, comme un signal pour réduire les dimensions ou déplacer l'analyse hors du système de supervision, et s'attendre à ce que la grande majorité des métriques n'aient aucun label. Un histogramme classique ingéré de façon classique multiplie le problème : chaque bucket configuré crée une série suffixée _bucket pour chaque combinaison de labels, qu'elle soit peuplée ou non.

Comment l'appliquer

• Nommer par préfixe, grandeur, unité, _total : queue_consumed_messages_total, job_last_success_timestamp_seconds.
• Utiliser des gabarits de route, pas des chemins bruts ; des classes ou codes de statut, pas des messages ; uniquement des valeurs de type énuméré.
• Avant d'ajouter un label, estimer ses valeurs distinctes et les multiplier par les combinaisons de labels existantes et par les buckets d'histogramme.
• Déplacer l'analyse par utilisateur ou par requête vers les journaux ou les traces, où une forte cardinalité est normale.
• Fixer une limite d'échantillons par cible lorsque le serveur en propose une (Prometheus : sample_limit dans la configuration de scrape) et alerter sur la croissance du nombre de séries, afin qu'un label défaillant soit détecté avant que le serveur ne le soit.

Pièges

Inscrire le sens d'un label dans le nom de la métrique (http_requests_get_total) casse l'agrégation. Mélanger secondes et millisecondes sous un même nom fait entrer les séries en collision silencieusement. Les noms de pod ou de conteneur sur des métriques applicatives sont bornés mais changent à chaque déploiement, créant chaque fois un nouvel ensemble de séries. Les histogrammes natifs modifient le modèle de coût des buckets ; le guide sur les histogrammes cité en explique les variantes.

Ce que fait une limite d'échantillons lorsqu'elle se déclenche

sample_limit est une dernière ligne de défense, pas un filtre : lorsqu'une cible la dépasse, Prometheus considère l'ensemble du scrape comme échoué, si bien que toutes les métriques de ce service disparaissent d'un coup et que les alertes qui les lisent deviennent silencieuses. L'utiliser en trois étapes. Supprimer ou agréger les labels connus pour être à risque dans metric_relabel_configs, afin qu'un label défaillant ne coûte qu'une métrique plutôt que la cible entière. Alerter sur la montée de scrape_samples_post_metric_relabeling vers la limite par cible, ainsi que sur prometheus_tsdb_head_series côté serveur, afin de voir la croissance avant la coupure. Fixer ensuite sample_limit bien au-dessus du nombre normal, de sorte que seul un emballement le déclenche. label_limit et les limites de longueur des labels font échouer le scrape de la même façon et méritent la même marge.