PromQL est le langage de requête sur lequel repose chaque partie de Prometheus qui lit des données : tableaux de bord, règles d’alerte, débogage ad hoc. Ce guide construit pas à pas une vraie requête : à partir d’un counter de requêtes décomposé par chemin, méthode et statut, trouver chaque chemin dont le taux d’erreurs dépasse 5 %.

Sélectionner des séries temporelles

L’expression PromQL la plus simple est juste un nom de métrique, qui renvoie la valeur actuelle de chaque série temporelle portant ce nom :

http_requests_total

Ajoutez des matchers de labels entre accolades pour restreindre à un sous-ensemble précis :

http_requests_total{status="500"}

Cela renvoie chaque série nommée http_requests_total dont le label status vaut exactement "500", quels que soient le chemin ou la méthode. Les matchers peuvent aussi faire de la correspondance par regex (status=~"5.." pour tout statut 5xx) et de la négation (status!="200"), entre autres opérateurs.

D’un counter à un taux

http_requests_total est un counter : il ne fait qu’augmenter, donc sa valeur brute (un grand nombre toujours croissant depuis le démarrage du processus) n’est pas ce que vous voulez réellement regarder. Ce que vous voulez, c’est à quelle vitesse il augmente, et c’est ce que calcule la fonction rate() : le taux d’augmentation moyen par seconde sur une fenêtre de temps donnée.

rate(http_requests_total{status="500"}[5m])

Cela renvoie, pour chaque série correspondante, le taux moyen par seconde d’erreurs 500 sur les 5 dernières minutes. Une fonction apparentée, irate(), calcule un taux instantané en n’utilisant que les deux derniers points de données de la plage, plutôt qu’une moyenne sur toute la fenêtre. irate() réagit plus vite aux pics soudains, mais elle est aussi plus bruitée et plus sensible à un seul scrape inhabituel ; rate() est la valeur par défaut recommandée pour les tableaux de bord et surtout pour l’alerting, où un signal plus lissé et moins sujet aux pics est généralement ce que vous voulez réellement. Utilisez irate() spécifiquement lorsque vous regardez un counter qui évolue vite sur une courte échelle de temps et que vous voulez voir les changements instantanés plutôt qu’une tendance lissée.

Agréger les labels qui ne vous intéressent pas

rate() renvoie encore un résultat par série temporelle d’origine, une ligne par combinaison unique de chemin, méthode et statut. Pour obtenir un seul nombre par chemin, sommé sur les méthodes et statuts existants, utilisez un opérateur d’agrégation :

sum by (path) (rate(http_requests_total{status="500"}[5m]))

sum by (path) (...) additionne les taux, en regroupant par le label path et en écartant tous les autres labels du résultat. C’est la forme générale de l’agrégation PromQL : choisir un opérateur (sum, avg, max, min, count, et d’autres), et une clause by (...) nommant les labels qui survivent dans le résultat.

Combiner des requêtes avec des opérateurs binaires

Pour calculer un taux d’erreurs en pourcentage, il faut deux requêtes agrégées, les requêtes en erreur et le total des requêtes, divisées l’une par l’autre :

sum by (path) (rate(http_requests_total{status="500"}[5m]))
/
sum by (path) (rate(http_requests_total[5m]))
* 100

PromQL fait correspondre les deux côtés d’une opération binaire par leurs labels restants, path ici, en calculant la division pour chaque paire correspondante au lieu de vous obliger à les aligner manuellement. Multiplier par 100 transforme le ratio obtenu en pourcentage.

Filtrer le résultat lui-même

Enveloppez toute l’expression pour ne conserver que les résultats qui franchissent réellement un seuil :

(
  sum by (path) (rate(http_requests_total{status="500"}[5m]))
  /
  sum by (path) (rate(http_requests_total[5m]))
  * 100
) > 5

Cela ne renvoie que les chemins dont le pourcentage d’erreurs calculé est actuellement supérieur à 5, ce qui est exactement la forme de requête que vous envelopperiez dans une règle d’alerte pour réveiller quelqu’un lorsqu’elle est vraie.

Transformer une requête en alerte

Une règle d’alerte est une expression PromQL accompagnée de métadonnées décrivant quoi faire lorsqu’elle renvoie quelque chose :

groups:
  - name: example-alerts
    rules:
      - alert: HighErrorRatePerPath
        expr: |
          (
            sum by (path) (rate(http_requests_total{status="500"}[5m]))
            /
            sum by (path) (rate(http_requests_total[5m]))
            * 100
          ) > 5
        for: 10m
        labels:
          severity: page
        annotations:
          summary: "Error rate above 5% on {{ $labels.path }}"

for: 10m exige que la condition reste vraie pendant 10 minutes avant que l’alerte se déclenche réellement, ce qui évite d’appeler quelqu’un pour une brève anomalie qui se résout d’elle-même. Prometheus évalue en continu des règles comme celle-ci et transmet à Alertmanager tout ce qui est actuellement en cours de déclenchement ; c’est le même PromQL que vous placeriez autrement directement dans un panneau Grafana, simplement enveloppé d’un nom, d’une durée et de métadonnées de routage.

Pour aller plus loin

Ceci couvre les instant vectors, les calculs de taux, l’agrégation et les opérateurs binaires, de quoi lire et écrire la grande majorité des requêtes que vous rencontrerez dans les tableaux de bord et alertes existants. PromQL va plus loin (fonctions sur range vectors au-delà de rate, sous-requêtes, davantage d’opérateurs d’agrégation), bien documenté dans la référence des requêtes de Prometheus, qu’il vaut la peine de garder ouverte pendant que vous écrivez vos premières vraies requêtes.