Chaque partie de Prometheus, scraping, stockage, PromQL, alerting, opère sur la même structure sous-jacente : une série temporelle, identifiée par un nom et un ensemble de labels, composée d’un flux de valeurs horodatées. Ce guide présente cette structure et le format texte brut que les cibles utilisent pour l’exposer.

Une série temporelle est un nom, un ensemble de labels et un flux d’échantillons

Un nom de métrique décrit ce qui est mesuré : http_requests_total, process_open_fds, node_memory_available_bytes. À lui seul, un nom de métrique n’est pas encore une unique série temporelle, c’est une famille que les labels subdivisent en séries individuelles. Les labels sont des paires clé-valeur attachées à une métrique : method="GET", status="500", path="/api/users". La combinaison d’un nom de métrique et d’un ensemble précis de valeurs de labels identifie exactement une série temporelle.

http_requests_total{method="GET", status="200", path="/api/users"}
http_requests_total{method="GET", status="500", path="/api/users"}
http_requests_total{method="POST", status="200", path="/api/orders"}

Ce sont trois séries temporelles distinctes qui partagent un même nom de métrique. Prometheus attache aussi automatiquement ses propres labels, identifiant la cible et le job dont provient une série, en plus des labels que l’application a elle-même choisi d’exposer.

Un échantillon (sample) est un point d’une série : un horodatage en millisecondes sur 64 bits (généralement l’instant du scrape) associé à une valeur à virgule flottante sur 64 bits. Une série est le flux continu de ces échantillons qui s’accumule, un par scrape, au fil du temps.

Les quatre types de métriques

Les bibliothèques clientes de Prometheus exposent quatre sortes de métriques, chacune signifiant quelque chose de différent au moment de l’interroger :

• Counter : une valeur qui ne fait qu’augmenter (ou repasse à zéro au redémarrage), comme un total cumulé de requêtes traitées. Vous ne lisez presque jamais la valeur brute d’un counter ; vous calculez un taux de variation dessus, traité dans le guide PromQL.
• Gauge : une valeur qui peut monter ou descendre, comme l’utilisation mémoire actuelle ou le nombre de requêtes en cours. Elle se lit directement, contrairement à un counter.
• Histogram : échantillonne des observations (durées de requêtes, tailles de réponses) dans des buckets configurables, et expose un compte et une somme à côté, ce qui permet de calculer des quantiles (comme la « latence au 95e percentile ») a posteriori à partir des données de buckets stockées.
• Summary : similaire à un histogram, mais calcule les quantiles côté client au moment de l’observation plutôt qu’à partir de buckets. Moins coûteux à interroger, mais les quantiles d’un summary ne peuvent pas être agrégés entre instances comme le peuvent les buckets d’un histogram, ce qui explique que les histograms soient le choix le plus courant pour tout ce que vous agrégerez sur une flotte.

Un type d’histogram natif, qui stocke les données d’histogram en pleine résolution plus efficacement que l’ancienne forme à buckets, est en développement actif depuis un moment ; consultez la documentation actuelle de Prometheus pour connaître sa maturité présente avant de vous y fier, car son niveau de prise en charge officielle a évolué au fil des dernières releases.

Le format d’exposition

Pour que Prometheus puisse scraper une cible, celle-ci sert ses valeurs actuelles via HTTP en texte brut, selon une disposition précise et volontairement simple :

# HELP http_requests_total Total number of HTTP requests handled.
# TYPE http_requests_total counter
http_requests_total{method="GET", status="200"} 8420
http_requests_total{method="GET", status="500"} 12

# HELP process_open_fds Number of open file descriptors.
# TYPE process_open_fds gauge
process_open_fds 27

Les lignes # HELP et # TYPE sont des commentaires fournissant la documentation et le type de la métrique ; toute autre ligne non commentée est la valeur actuelle d’une série, sous la forme d’un nom de métrique, de ses labels entre accolades, et de la valeur elle-même. Comme il ne s’agit jamais que d’un instantané, une ligne par série montrant sa valeur à cet instant, il n’y a pas d’historique dans une réponse de scrape ; l’historique n’existe que lorsque Prometheus a scrapé la même série de façon répétée dans le temps et stocké chaque résultat.

La simplicité du format est délibérée : il est conçu pour être trivial à générer même sans bibliothèque cliente, ce qui rend réaliste d’extraire des métriques Prometheus de presque n’importe quoi, pas seulement des logiciels disposant d’une prise en charge officielle par bibliothèque.

Voyez-le par vous-même

Comme le scraping n’est qu’un simple GET HTTP, vous pouvez voir les métriques actuelles de n’importe quelle cible directement dans un navigateur ou avec curl, sans serveur Prometheus :

curl http://localhost:9100/metrics   # une instance de node_exporter, par exemple

Cette sortie est exactement ce que Prometheus reçoit lui-même à chaque scrape, ce qui en fait une première étape de dépannage réellement utile : si une cible n’apparaît pas correctement dans Prometheus, vérifier directement sa sortie brute /metrics vous dit si le problème vient de la cible ou de la configuration de scraping de Prometheus.

D’où viennent les labels, et pourquoi ils comptent par la suite

Les propres labels d’une cible (quel endpoint, quelle méthode, quel code de statut) proviennent de la façon dont l’application ou l’exporter s’est instrumenté. Prometheus ajoute les siens par-dessus, identifiant le job et l’instance précise dont une série a été scrapée. Ensemble, ces labels sont ce sur quoi s’appuient l’agrégation et le filtrage de PromQL, vous permettant de demander « le taux d’erreurs sur toutes les instances » ou « le taux de requêtes pour ce seul chemin » sur les mêmes données sous-jacentes, ce que couvre précisément le guide suivant de cette série.