Maintenir Prometheus sur le long terme
Un Prometheus qui dure se joue sur trois chiffres : séries actives, échantillons par seconde, espace consommé. Tout le reste en découle.
Un disque à 92 % et aucune métrique ajoutée depuis six mois
Le graphe de saturation disque passe au rouge un mardi matin. Personne n'a touché au code depuis février, le trafic est stable, et pourtant prometheus_tsdb_head_series a triplé. La cause tient en un label : un request_id ajouté par un exporter, qui a transformé chaque requête en série temporelle distincte.
Prometheus ne stocke pas des lignes, il stocke des séries identifiées par un nom et un jeu de labels. Chaque valeur de label inédite crée une série, avec son entrée d'index et son chunk. La facture arrive des mois après la ligne de code coupable.
Maintenir Prometheus sur le long terme, ce n'est donc pas surveiller Prometheus. C'est tenir un budget de cardinalité, une politique de rétention et un rituel de mise à jour. Trois disciplines, et aucune n'est vraiment technique.
Compter les séries avant de promettre une rétention
La première commande à taper sur une instance qui vieillit tient en une ligne. Elle classe les métriques par nombre de séries, ce que le graphe de stockage ne montre jamais.
topk(10, count by (__name__) ({__name__=~".+"}))Sur une instance saine, le top 10 reste dominé par les métriques d'infrastructure classiques : node_cpu_seconds_total, container_memory_working_set_bytes, http_request_duration_seconds_bucket. Si une métrique métier apparaît en tête, tu as trouvé la fuite.
Le deuxième réflexe est de descendre d'un niveau, par job, pour identifier le coupable côté scrapers plutôt que côté code.
topk(10, count by (job) ({__name__=~".+"}))Pour les chiffres exacts, promtool lit directement les blocs TSDB. La commande affiche la cardinalité réelle, la taille des blocs et les labels les plus coûteux.
promtool tsdb analyze /var/lib/prometheus
| Symptôme | Cause probable | Correctif durable |
|---|---|---|
| RAM du head qui grimpe sans trafic | Label à forte cardinalité (user_id, request_id, pod_name) | metric_relabel_configs avec labeldrop |
| Requêtes lentes sur 7 jours | Trop de séries agrégées à la volée | Recording rules pré-agrégées |
| Disque plein alors que la rétention est respectée | Compactions en cours + WAL | Marge de 15–20 % sur le disque |
| Blocs supprimés en retard | Nettoyage asynchrone des blocs expirés | Compter jusqu'à 2 h de décalage |
Le correctif se pose dans le scrape config, pas dans le dashboard. Il supprime le label à l'ingestion, ce qui élimine la série avant qu'elle n'existe.
scrape_configs:
- job_name: api
metric_relabel_configs:
- regex: (request_id|user_id|trace_id)
action: labeldropCette suppression a un coût assumé : tu perds la corrélation fine avec les traces. C'est précisément le compromis que décrit le vrai coût de l'observabilité — la précision se paie en cardinalité.
Dimensionner la rétention avec la formule, pas à l'intuition
La documentation Prometheus donne une formule simple, et presque personne ne l'applique. Elle relie espace disque, durée de rétention, débit d'échantillons et taille moyenne par échantillon.
needed_disk_space = retention_seconds * samples_per_second * bytes_per_samplePrometheus compresse à 1–2 octets par échantillon en moyenne. Avec 80 000 échantillons par seconde et 1,5 octet, 15 jours demandent environ 145 Gio, quand la même charge sur 90 jours en réclame 870.
Trois flags pilotent tout : --storage.tsdb.retention.time, --storage.tsdb.retention.size et --storage.tsdb.path. Si tu n'en poses aucun, la rétention temporelle vaut 15 jours par défaut.
prometheus \
--storage.tsdb.path=/var/lib/prometheus \
--storage.tsdb.retention.time=30d \
--storage.tsdb.retention.size=180GB \
--storage.tsdb.wal-compressionQuand les deux politiques coexistent, la première qui déclenche gagne. Poser une limite en taille évite le scénario classique : la rétention temporelle est respectée, mais le disque explose parce que la cardinalité a doublé entre-temps.
La recommandation officielle est de plafonner retention.size à 80–85 % du disque alloué. Les 15–20 % restants absorbent les compactions, qui gardent blocs sources et bloc compacté sur le disque en même temps.
Deux détails qui coûtent cher en production. Les blocs expirés sont supprimés en arrière-plan, avec jusqu'à deux heures de retard. Et le TSDB ne supporte pas les systèmes de fichiers non POSIX : pas de NFS, pas d'EFS, même si ça monte.
Des recording rules qui survivent aux années
Une recording rule mal nommée devient un mystère pour l'équipe suivante, et une rule mal calibrée devient un générateur de séries. La convention de nommage résout le premier problème : niveau, métrique, opérations.
groups:
- name: api-slo
interval: 30s
rules:
- record: job:http_requests:rate5m
expr: sum by (job) (rate(http_requests_total[5m]))
- record: job:http_errors_ratio:rate5m
expr: |
sum by (job) (rate(http_requests_total{code=~"5.."}[5m]))
/
sum by (job) (rate(http_requests_total[5m]))Une rule dont le résultat dépasse quelques milliers de séries est une rule à revoir. Agrège au niveau dont tu as besoin pour les dashboards et les alertes, pas au niveau le plus fin « au cas où ».
Valide chaque fichier avant de recharger. promtool attrape la syntaxe et, surtout, les expressions qui ne renvoient jamais rien.
promtool check rules /etc/prometheus/rules/*.yml
promtool check config /etc/prometheus/prometheus.ymlAjoute des tests unitaires aux rules critiques. Un fichier de test décrit des séries d'entrée et les valeurs attendues : la rule devient vérifiable en CI, exactement comme du code applicatif.
rule_files:
- rules/api-slo.yml
evaluation_interval: 30s
tests:
- interval: 1m
input_series:
- series: 'http_requests_total{job="api",code="200"}'
values: '0+60x10'
promql_expr_test:
- expr: job:http_requests:rate5m
eval_time: 5mLe rechargement à chaud suppose --web.enable-lifecycle, donc un endpoint /-/reload sans authentification. Garde l'interface liée à 127.0.0.1 ou derrière un reverse proxy qui filtre, sinon n'importe qui peut recharger ta config.
Mettre à jour : 3.15.1, LTS 3.13, et les flags disparus
La dernière version stable au moment d'écrire est la 3.15.1, publiée le 21 octobre 2026. La branche LTS est la 3.13, et c'est elle qu'il faut viser pour une infra que tu ne touches pas chaque semaine.
Le passage en 3.x n'est pas une simple montée de version. Des feature flags ont disparu et leur comportement est devenu le défaut : remote-write-receiver s'active désormais par --web.enable-remote-write-receiver, et le mode agent par un flag dédié --agent.
Le changement le plus vicieux concerne PromQL. En 3.x, le point des expressions régulières matche les retours à la ligne : un .* dans un matcher peut désormais capturer des labels qui contenaient un saut de ligne, et une alerte qui filtrait proprement en 2.55 se met à hurler sur des séries inattendues.
La procédure qui évite le week-end gâché tient en quatre étapes. Épingler un tag précis, valider la config avec promtool, dérouler sur une instance jumelle qui scrape les mêmes cibles, puis basculer. Le format TSDB reste lisible en arrière, mais une fois les blocs réécrits par une version récente, le retour arrière n'est plus garanti.
| Étape | Commande | Ce que tu attrapes |
|---|---|---|
| Valider | promtool check config | Flags et champs supprimés |
| Tester | promtool test rules | Rules cassées par le nouveau moteur |
| Comparer | Instance jumelle, mêmes cibles | Écarts de cardinalité et de valeurs |
| Basculer | Bascule DNS ou LB | Retour arrière possible sur l'ancienne |
Le guide de migration officiel liste les changements incompatibles version par version. Le lire en entier prend vingt minutes et évite la majorité des incidents.
Sauvegarder par snapshot, pas par rsync
Copier le répertoire data/ à chaud donne une sauvegarde incohérente. Les échantillons les plus récents vivent dans le WAL et dans les chunks mappés en mémoire, pas encore compactés en blocs.
L'API de snapshot produit une copie stable, sans arrêter le serveur.
curl -X POST http://127.0.0.1:9090/api/v1/admin/tsdb/snapshot
# {"status":"success","data":{"name":"20261105T060000Z-1a2b3c4d"}}
tar czf prometheus-$(date +%F).tgz -C /var/lib/prometheus/snapshots 20261105T060000Z-1a2b3c4dSans snapshot, exclus au minimum wal/, chunks_head/ et wbl/. Tu perds les dernières heures, mais la restauration reste cohérente.
Une sauvegarde jamais restaurée n'est pas une sauvegarde. Le test utile consiste à démarrer une instance jetable sur la copie et à lancer une requête sur une date ancienne.
Sortir l'historique : Thanos, Mimir, ou rester local
Prometheus local n'est ni répliqué ni clusterisé — Thanos a été construit exactement pour ce manque. C'est un choix assumé, pas un défaut : la documentation rappelle qu'avec une architecture correcte, plusieurs années de données tiennent sur un seul nœud.
Le passage à un stockage long terme se justifie par trois besoins concrets : garder plus de 90 jours, survivre à la perte d'un nœud, ou interroger plusieurs clusters depuis une seule API.
| Option | Quand c'est le bon choix | Coût caché |
|---|---|---|
| Prometheus local seul | Un cluster, moins de 90 jours, une équipe | Aucune haute disponibilité |
| Thanos (sidecar + object storage) | Plusieurs Prometheus, historique long, budgets maîtrisés | Latence de requête sur le long terme |
| Grafana Mimir | Multi-tenant, très gros volumes | Exploitation d'un cluster stateful |
| Remote write vers un SaaS | Équipe réduite, pas d'exploitation stockage | Facture proportionnelle à la cardinalité |
Le facteur décisif reste la cardinalité, pas le volume. Un million de séries actives coûte cher partout, en RAM comme en facture SaaS, alors que la même donnée agrégée en recording rules coûte dix fois moins.
Si tu ajoutes de l'OpenTelemetry à côté, garde une règle : Prometheus reste la source des métriques, le backend de traces reste la source des traces, et le trace_id fait le lien sans être stocké comme label. La mise en place est décrite dans implémenter OpenTelemetry dans tes projets.
FAQ
Combien de temps garder les métriques ?
La bonne question est : quelle décision prends-tu avec des données de six mois ? Pour les tendances de capacité, 90 jours suffisent presque toujours. Au-delà, l'agrégation horaire dans un stockage long terme coûte moins cher que la rétention brute.
Prometheus tient-il un million de séries actives ?
Oui sur une machine correctement dimensionnée, mais ce n'est pas un objectif en soi. Mesure prometheus_tsdb_head_series avant et après chaque ajout de cible, et traite toute croissance supérieure à 10 % par mois comme une alerte.
Faut-il activer les native histograms ?
Elles sont stables depuis la 3.9 et le scraping s'active via scrape_native_histograms. À précision égale, elles génèrent bien moins de séries que les buckets classiques. Le frein est côté backend : vérifie que ton stockage long terme les supporte avant de basculer.
Quel intervalle de scrape choisir ?
15 secondes est un défaut raisonnable, 30 secondes divise le volume par deux. Ne descends en dessous de 10 secondes que si une alerte l'exige vraiment : chaque division de l'intervalle double le débit d'échantillons et la facture.
Le budget avant la technique
Un Prometheus qui dure, c'est trois chiffres suivis chaque mois : séries actives, échantillons par seconde, espace consommé. Le reste — flags, upgrades, stockage distant — se déduit de ces trois-là.
La panne la plus fréquente n'est pas un bug de Prometheus. C'est une instance qu'on a laissé grossir sans jamais recompter.