Cardinalité Prometheus : Éviter l'Explosion de Séries

Un label de trop peut multiplier vos séries temporelles par un million. Voici les mécanismes, les pièges et les solutions.

Prometheus stocke une série temporelle pour chaque combinaison unique de nom de métrique et de labels. Un label mal choisi transforme une métrique légère en un monstre qui mange votre RAM. Comprendre la cardinalité, c'est comprendre comment Prometheus voit votre monde.

Qu'est-ce qu'une série temporelle ?

Une série temporelle est l'identifiant unique formé par un nom de métrique et un ensemble de paires label=valeur. http_requests_total{method="GET", status="200"} et http_requests_total{method="POST", status="500"} sont deux séries distinctes. Prometheus stocke, indexe et compresse chacune indépendamment. Chaque scrape ajoute un nouveau point à chaque série active.

L'explosion combinatoire

La cardinalité totale est le produit des cardinalités de chaque label. Une métrique avec method (5 valeurs) × status (50 valeurs) × endpoint (200 routes) × region (3 zones) × pod (100 pods) produit 5 × 50 × 200 × 3 × 100 = 150 000 000 séries. Un seul label user_id avec 10 millions d'utilisateurs actifs donne 10 millions de séries pour cette seule métrique.

Impact mémoire et disque

Prometheus maintient un "head block" en RAM pour les données récentes (typiquement 2h). Chaque série active y occupe environ 1–2 Ko (métadonnées, index, données compressées). 1 million de séries actives = 1–2 Go de RAM rien que pour le head block. Le stockage disque tourne autour de 1–2 octets par échantillon avec la compression Gorilla : à 15 s d'intervalle, c'est ~11 Ko par série et par jour.

Les suspects habituels

Certains labels sont quasi-universellement dangereux : pod (recréé à chaque déploiement, cardinalité croissante), user_id, request_id, trace_id, adresse IP. Kubernetes injecte souvent ces labels automatiquement via le service discovery. Les histogrammes multiplient la cardinalité par le nombre de buckets le (typiquement 10–15). La règle d'or : si la valeur d'un label peut être un identifiant unique, ne l'utilisez pas comme label.

Stratégies de réduction

Agréger au moment du scrape plutôt qu'après. Utiliser des recording rules pour pré-calculer les agrégations fréquentes. Limiter les labels via allow-list dans les jobs Prometheus. Les histogrammes natifs (Prometheus 2.40+) réduisent considérablement la cardinalité des histogrammes. Définir un "budget de cardinalité" par équipe et le surveiller via la métrique prometheus_tsdb_head_series.

Pièges courants

! Ajouter un label 'pour le debug' : un label temporaire de diagnostic peut décupler votre cardinalité en production.
! Faire confiance au service discovery Kubernetes sans filtrage : les labels de pod créent une cardinalité fantôme à chaque déploiement.
! Négliger les histogrammes : chaque bucket le se comporte comme un label — un histogramme à 15 buckets avec 3 autres labels explose vite.