PromQL (Prometheus Query Language) est le langage de requête de Prometheus. Ce guide vous accompagne des bases aux requêtes avancées, avec des exemples concrets que vous pouvez tester immédiatement.
Premiers pas avec PromQL
Section intitulée « Premiers pas avec PromQL »Accédez à l’interface Prometheus (http://localhost:9090) et utilisez l’onglet
Graph pour tester vos requêtes.
Requête la plus simple
Section intitulée « Requête la plus simple »Tapez le nom d’une métrique pour voir toutes ses séries :
upRésultat : toutes les séries de la métrique up, une par target scrapée.
up{instance="localhost:9090", job="prometheus"} 1up{instance="node1:9100", job="node"} 1up{instance="node2:9100", job="node"} 0Filtrer avec les labels
Section intitulée « Filtrer avec les labels »Les sélecteurs de labels filtrent les séries :
up{job="node"}Opérateurs de matching :
| Opérateur | Description | Exemple |
|---|---|---|
= | Égalité exacte | job="prometheus" |
!= | Différent de | job!="test" |
=~ | Regex match | job=~"node.*" |
!~ | Regex not match | job!~"test.*" |
Exemples pratiques :
# Toutes les requêtes HTTP sauf les 200http_requests_total{status!="200"}
# Méthodes GET ou POSThttp_requests_total{method=~"GET|POST"}
# Namespaces commençant par "prod"container_memory_usage_bytes{namespace=~"prod.*"}Types de données
Section intitulée « Types de données »PromQL manipule quatre types de données :
| Type | Description | Exemple |
|---|---|---|
| Instant vector | Valeurs actuelles (un point par série) | up |
| Range vector | Valeurs sur une période | up[5m] |
| Scalar | Nombre flottant | 3.14 |
| String | Chaîne (rarement utilisé) | "hello" |
Instant vector
Section intitulée « Instant vector »C’est le type le plus courant. Chaque série a une seule valeur (la dernière).
node_memory_MemAvailable_bytesRange vector
Section intitulée « Range vector »Sélectionne toutes les valeurs sur une période. Nécessaire pour les
fonctions comme rate().
http_requests_total[5m]Périodes disponibles : s (secondes), m (minutes), h (heures), d (jours),
w (semaines), y (années).
Opérateurs
Section intitulée « Opérateurs »Opérateurs arithmétiques
Section intitulée « Opérateurs arithmétiques »Les opérateurs classiques fonctionnent sur les séries :
# Mémoire utilisée en pourcentage(node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes * 100
# Conversion bytes → gigabytesnode_filesystem_size_bytes / 1024 / 1024 / 1024| Opérateur | Description |
|---|---|
+ | Addition |
- | Soustraction |
* | Multiplication |
/ | Division |
% | Modulo |
^ | Puissance |
Opérateurs de comparaison
Section intitulée « Opérateurs de comparaison »Retournent 1 (vrai) ou filtrent les séries :
# Instances avec CPU > 80%instance:cpu_usage:percent > 80
# Garder uniquement les séries au-dessus du seuilhttp_request_duration_seconds > 0.5| Opérateur | Description |
|---|---|
== | Égal |
!= | Différent |
> | Supérieur |
< | Inférieur |
>= | Supérieur ou égal |
<= | Inférieur ou égal |
Opérateurs logiques
Section intitulée « Opérateurs logiques »Pour combiner des vecteurs :
# Séries présentes dans les deux (intersection)metric_a and metric_b
# Séries présentes dans l'un ou l'autre (union)metric_a or metric_b
# Séries de A absentes de Bmetric_a unless metric_bFonctions essentielles
Section intitulée « Fonctions essentielles »rate() — Taux de variation
Section intitulée « rate() — Taux de variation »La fonction la plus importante. Calcule le taux par seconde d’un counter.
# Requêtes par seconde (sur 5 minutes)rate(http_requests_total[5m])irate() — Taux instantané
Section intitulée « irate() — Taux instantané »Comme rate() mais utilise uniquement les 2 derniers points. Plus réactif
mais plus bruité.
# Taux instantané (derniers 5 min de données)irate(http_requests_total[5m])increase() — Augmentation totale
Section intitulée « increase() — Augmentation totale »Nombre total d’augmentations sur la période.
# Nombre de requêtes sur 1 heureincrease(http_requests_total[1h])sum(), avg(), min(), max() — Agrégations
Section intitulée « sum(), avg(), min(), max() — Agrégations »Agrègent plusieurs séries en une.
# Total des requêtes (toutes instances)sum(rate(http_requests_total[5m]))
# Moyenne de mémoire par nodeavg(node_memory_MemAvailable_bytes)
# Maximum de CPUmax(instance:cpu_usage:percent)Agrégation par label
Section intitulée « Agrégation par label »Utilisez by ou without pour contrôler l’agrégation :
# Somme par jobsum by(job) (rate(http_requests_total[5m]))
# Somme en ignorant le label instancesum without(instance) (rate(http_requests_total[5m]))histogram_quantile() — Percentiles
Section intitulée « histogram_quantile() — Percentiles »Calcule les percentiles depuis un histogram.
# P95 de latence par jobhistogram_quantile(0.95, sum by(job, le) (rate(http_request_duration_seconds_bucket[5m])))
# P99 globalhistogram_quantile(0.99, sum by(le) (rate(http_request_duration_seconds_bucket[5m])))Fonctions mathématiques
Section intitulée « Fonctions mathématiques »| Fonction | Description | Exemple |
|---|---|---|
abs() | Valeur absolue | abs(delta(temp[1h])) |
ceil() | Arrondi supérieur | ceil(value) |
floor() | Arrondi inférieur | floor(value) |
round() | Arrondi | round(value, 0.1) |
ln() | Logarithme naturel | ln(value) |
log2() | Log base 2 | log2(value) |
log10() | Log base 10 | log10(value) |
sqrt() | Racine carrée | sqrt(value) |
Fonctions temporelles
Section intitulée « Fonctions temporelles »| Fonction | Description |
|---|---|
time() | Timestamp Unix actuel |
timestamp() | Timestamp de chaque sample |
day_of_week() | Jour de la semaine (0-6) |
hour() | Heure (0-23) |
# Alerte uniquement en heures ouvréesup == 0 and hour() >= 9 and hour() <= 18Fonctions sur range vectors
Section intitulée « Fonctions sur range vectors »| Fonction | Description |
|---|---|
avg_over_time() | Moyenne sur la période |
min_over_time() | Minimum sur la période |
max_over_time() | Maximum sur la période |
sum_over_time() | Somme sur la période |
count_over_time() | Nombre de points |
stddev_over_time() | Écart-type |
changes() | Nombre de changements |
resets() | Nombre de resets (counter) |
delta() | Différence premier-dernier |
deriv() | Dérivée (pente) |
predict_linear() | Prédiction linéaire |
# Moyenne de CPU sur 1 heureavg_over_time(instance:cpu_usage:percent[1h])
# Prédiction : dans 4h, espace disquepredict_linear(node_filesystem_avail_bytes[6h], 4*3600)Requêtes avancées
Section intitulée « Requêtes avancées »CPU usage
Section intitulée « CPU usage »# Pourcentage CPU utilisé par instance100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)Explication :
node_cpu_seconds_total{mode="idle"}: temps CPU en idlerate(...[5m]): taux par seconde sur 5 minavg by(instance): moyenne des cores par machine* 100: conversion en pourcentage100 - ...: usage = 100% - idle
Mémoire utilisée
Section intitulée « Mémoire utilisée »# Pourcentage mémoire utilisée(1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) * 100Taux d’erreurs HTTP
Section intitulée « Taux d’erreurs HTTP »# Taux d'erreurs 5xx sur le totalsum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) * 100Latence P95
Section intitulée « Latence P95 »# P95 par endpointhistogram_quantile(0.95, sum by(handler, le) (rate(http_request_duration_seconds_bucket[5m])))Prédiction d’espace disque
Section intitulée « Prédiction d’espace disque »# Prédiction : disque plein dans combien de temps (secondes)(node_filesystem_avail_bytes / node_filesystem_size_bytes) / deriv(node_filesystem_avail_bytes[6h]) * -1Top 5 des consommateurs
Section intitulée « Top 5 des consommateurs »# Top 5 pods par mémoiretopk(5, container_memory_usage_bytes{container!=""})Requêtes avec offset
Section intitulée « Requêtes avec offset »Comparer avec le passé :
# Différence avec il y a 1 semainerate(http_requests_total[5m]) - rate(http_requests_total[5m] offset 1w)Vector matching
Section intitulée « Vector matching »Quand vous combinez deux vecteurs, PromQL fait du matching par labels.
One-to-one (défaut)
Section intitulée « One-to-one (défaut) »Chaque série d’un côté matche exactement une série de l’autre.
# Même labels des deux côtésmetric_a / metric_bIgnoring / on
Section intitulée « Ignoring / on »Spécifie quels labels utiliser pour le matching :
# Matcher uniquement sur le label "job"metric_a / on(job) metric_b
# Matcher en ignorant le label "instance"metric_a / ignoring(instance) metric_bGroup modifiers
Section intitulée « Group modifiers »Pour le one-to-many ou many-to-one :
# Chaque série de B matchée à une série de Ametric_a / on(job) group_left metric_bBonnes pratiques
Section intitulée « Bonnes pratiques »Nommage des métriques
Section intitulée « Nommage des métriques »Suivez la convention Prometheus :
<namespace>_<name>_<unit>_<suffix>Exemples :
http_requests_total(counter)http_request_duration_seconds(histogram)node_memory_MemAvailable_bytes(gauge)
Éviter les pièges courants
Section intitulée « Éviter les pièges courants »❌ Mauvais : rate() sur un gauge
rate(node_memory_MemAvailable_bytes[5m]) # FAUX✅ Correct : deriv() pour un gauge
deriv(node_memory_MemAvailable_bytes[5m])❌ Potentiel NaN
rate(errors[5m]) / rate(requests[5m])✅ Protégé
rate(errors[5m]) / (rate(requests[5m]) > 0)ou
rate(errors[5m]) / rate(requests[5m]) or vector(0)❌ Cardinalité explosive
sum by(user_id) (http_requests_total) # Millions de séries✅ Agrégation raisonnable
sum by(endpoint, status) (http_requests_total)Performance
Section intitulée « Performance »- Utilisez les recording rules pour les requêtes complexes fréquentes
- Limitez la période :
[5m]est souvent suffisant - Agrégez tôt :
sum by(job) (rate(...))plutôt que calculs sur toutes les séries - Évitez
.*dans les regex : préférez des valeurs exactes
Cheatsheet
Section intitulée « Cheatsheet »# === COUNTERS ===rate(counter[5m]) # Taux par secondeincrease(counter[1h]) # Augmentation totaleirate(counter[5m]) # Taux instantané
# === AGRÉGATIONS ===sum(metric) # Totalavg(metric) # Moyennemax(metric) # Maximummin(metric) # Minimumcount(metric) # Nombre de sériessum by(label) (metric) # Grouper par label
# === PERCENTILES ===histogram_quantile(0.95, sum by(le) (rate(histogram_bucket[5m])))
# === TEMPS ===avg_over_time(metric[1h]) # Moyenne sur 1hmax_over_time(metric[24h]) # Max sur 24hpredict_linear(metric[6h], 3600) # Prédiction dans 1h
# === COMPARAISON ===metric > 80 # Filtremetric > bool 80 # Retourne 0/1topk(5, metric) # Top 5bottomk(3, metric) # Bottom 3
# === LABELS ===label_replace(metric, "new", "$1", "old", "(.*)")label_join(metric, "new", ",", "label1", "label2")À retenir
Section intitulée « À retenir »- rate() pour les counters, deriv() pour les gauges
- by() et without() contrôlent l’agrégation
- histogram_quantile() pour les percentiles
- Protégez les divisions contre le zéro
- Testez dans l’UI avant de mettre en alerte
Prochaines étapes
Section intitulée « Prochaines étapes » Alertmanager Transformer vos requêtes en alertes
Configuration Recording rules pour optimiser