Aller au contenu

GUIDE TECHNIQUE · PROMETHEUS

Écrire des requêtes PromQL

Construire des requêtes PromQL fiables pour un taux de requêtes, un ratio d'erreurs et un percentile de latence, en contrôlant les labels et les unités disponibles.

Niveau Intermédiaire5 min de lecture— vuesPrometheus

L’ESSENTIEL EN BREF

Les étapes clés

Ce guide présente 4 étapes, de « Inventorier les séries et leurs labels » à « Éprouver les requêtes sur plusieurs fenêtres ».

Avant de commencer : Environnement de recette Prometheus autorisé, indépendant des configurations de production.

01 · CADRAGE

Périmètre et résultat visé

Résultat attendu : Le débit est exprimé en requêtes/s et le ratio d'erreurs conserve un dénominateur explicite.

Public concerné : Ingénieurs DevOps, SRE, administrateurs plateforme et support N2/N3.

Environnement et versions

Prometheus avec PromQL ; les exemples HTTP nécessitent de vrais compteurs et histogrammes instrumentés, dont les noms peuvent varier selon la bibliothèque.

02 · AVANT DE COMMENCER

Prérequis et points de contrôle

Un Prometheus disposant de http_requests_total et d’un histogramme classique http_request_duration_seconds_bucket avec labels connus et du trafic de recette.

  • Environnement de recette Prometheus autorisé, indépendant des configurations de production.
  • Accès et permissions minimales vérifiés pour le scénario « prometheus promql latence erreurs ».
  • Jeu de données non sensible et critères de réussite définis avant les modifications.

Votre environnement de départ

Environnement
Un Prometheus de recette ou le laboratoire complet créé dans le guide d’installation/Alertmanager.
Outils
Navigateur, curl ; Docker Compose pour les laboratoires complets ; promtool fourni par l’image.
Comptes et droits
Création de conteneurs pour les parcours Compose ; édition/rechargement de la configuration pour un serveur existant.
Réseau et accès
Prometheus vers les endpoints /metrics ; Prometheus vers Alertmanager puis Alertmanager vers le récepteur ; ports locaux selon les fichiers fournis.

Contrôles avant de commencer

Où effectuer le contrôle : Console Prometheus

Commandes et configuration
up
# Exécuter cette expression dans Query après démarrage du laboratoire.

Résultat attendu : Les labels job/instance et l’état de chaque cible de recette sont identifiés.

03 · VUE D’ENSEMBLE

Comprendre l’architecture et les flux

ARCHITECTURE TECHNIQUEComprendre la chaîne de bout en bout
01Endpoint /metrics
02Prometheus scrape
03PromQL
04Dashboard RUN
Les compteurs permettent de calculer des débits avec rate ; les histogrammes classiques exposent des buckets cumulés incluant le label le, nécessaires à histogram_quantile.

04 · TUTORIEL

Procédure complète, étape par étape

Suivez les étapes dans l’ordre et contrôlez chaque résultat avant de poursuivre. Renseignez les paramètres adaptés à votre environnement.

01

ÉTAPE 1 / 4

Inventorier les séries et leurs labels

Une requête PromQL pertinente part des métriques réellement exposées par le service.

  1. Vérifier les noms et labels de http_requests_total et http_request_duration_seconds_bucket, ou leurs équivalents.
  2. Identifier le service, les codes d'erreur et la fenêtre d'observation pertinentes.
Ce qui se passe à cette étape
1Endpoint /metrics
2Prometheus scrape
3PromQL

À vérifier : Les compteurs et leurs unités sont connus ; aucune métrique inexistante n'est supposée.

Point de vigilance : Conserver le moindre privilège et ne jamais afficher de secret.

02

ÉTAPE 2 / 4

Calculer le débit et le taux d'erreurs

rate() sur un compteur estime des évolutions par seconde, pas un nombre brut de requêtes.

  1. Vérifier que job=app-lab et le label status existent réellement ; remplacer leurs noms/valeurs dans toutes les requêtes si votre instrumentation diffère.
  2. La première expression renvoie un débit en requêtes/seconde. La seconde renvoie une proportion entre 0 et 1 de réponses 5xx ; multiplier par 100 uniquement pour un affichage en pourcentage.
  3. Le or vector(0) couvre le cas où aucun compteur 5xx n’existe dans un trafic présent. Si le dénominateur est absent ou nul, le résultat n’est pas un taux d’erreur mesuré à zéro ; traiter ce cas séparément.
Commandes et configuration
sum(rate(http_requests_total{job="app-lab"}[5m]))
(sum(rate(http_requests_total{job="app-lab",status=~"5.."}[5m])) or vector(0))
  / sum(rate(http_requests_total{job="app-lab"}[5m]))
Ce qui se passe à cette étape
1Endpoint /metrics
2Prometheus scrape
3PromQL

À vérifier : Le débit est exprimé en requêtes/s et le ratio d'erreurs conserve un dénominateur explicite.

Point de vigilance : Tester la configuration sur une instance ou un projet de recette, sans modifier la production.

03

ÉTAPE 3 / 4

Calculer un percentile à partir des buckets

histogram_quantile() ne s'applique pas directement à une simple moyenne.

  1. Agréger les buckets par le et, si nécessaire, par service avant d'appeler histogram_quantile(0.95,...).
  2. Vérifier l'unité de la métrique de durée et vérifier qu'un bucket +Inf est présent.
  3. L’exemple est un histogramme classique avec label le et unité secondes. Contrôler le bucket +Inf ; ne pas transposer tel quel à une instrumentation utilisant une autre unité ou un histogramme natif.
Commandes et configuration
histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket{job="app-lab"}[5m])))
Ce qui se passe à cette étape
1Prometheus scrape
2PromQL
3Dashboard RUN

À vérifier : Le p95 estimé est interprété dans la bonne unité et sur le bon service.

Point de vigilance : Conserver le moindre privilège et ne jamais afficher de secret.

04

ÉTAPE 4 / 4

Éprouver les requêtes sur plusieurs fenêtres

Un trafic faible ou des labels incohérents peuvent rendre les résultats instables.

  1. Comparer une fenêtre courte et une fenêtre plus longue en annotant les changements de trafic.
  2. Contrôler le comportement en absence d'échantillons et documenter les limites de précision du quantile.
Ce qui se passe à cette étape
1Prometheus scrape
2PromQL
3Dashboard RUN

À vérifier : Les requêtes sont reproductibles et ne transforment pas une absence de données en zéro.

Point de vigilance : Ne jamais supprimer de ressource partagée pendant la recette.

RÉFÉRENCES TECHNIQUES

Documentation officielle

Retrouvez les fonctionnalités, les paramètres et les matrices de compatibilité de Prometheus.

Consulter la documentation officielle

05 · RECETTE

Comment vérifier que tout fonctionne ?

Résultat attenduContrôles avant de considérer la procédure terminée
01

Le débit est exprimé en requêtes/s et le ratio d'erreurs conserve un dénominateur explicite.

02

Le p95 estimé est interprété dans la bonne unité et sur le bon service.

03

Les requêtes sont reproductibles et ne transforment pas une absence de données en zéro.

06 · DIAGNOSTIC

Problèmes fréquents et résolution

Le signal attendu n'apparaît pas

Cause probable : rate() sur un compteur estime des évolutions par seconde, pas un nombre brut de requêtes.

Que faire : Construire le ratio des réponses en erreur en filtrant les labels de statut réellement présents. Vérifier l'unité de la métrique de durée et vérifier qu'un bucket +Inf est présent.

La vérification donne un résultat incohérent

Cause probable : histogram_quantile() ne s'applique pas directement à une simple moyenne.

Que faire : Agréger les buckets par le et, si nécessaire, par service avant d'appeler histogram_quantile(0.95,...). Comparer une fenêtre courte et une fenêtre plus longue en annotant les changements de trafic.

Une action est refusée

Cause probable : Les permissions ou la portée de l'accès ne sont pas adaptées au laboratoire

Que faire : Vérifier le droit précis et le périmètre, sans élever globalement les privilèges.

07 · QUESTIONS PRATIQUES

Questions fréquentes

Comment reconnaître une configuration valide ?

Le débit est exprimé en requêtes/s et le ratio d'erreurs conserve un dénominateur explicite.

Quel contrôle prouve un fonctionnement réel ?

Le p95 estimé est interprété dans la bonne unité et sur le bon service.

Que faire en cas d'échec ?

Comparer une fenêtre courte et une fenêtre plus longue en annotant les changements de trafic. Contrôler le comportement en absence d'échantillons et documenter les limites de précision du quantile.

AUTRES TECHNOLOGIES

Guides complémentaires

Tous les guides Prometheus

VOTRE ENVIRONNEMENT

Besoin d’aller plus loin sur votre environnement ?

Échangeons sur votre environnement Prometheus : pratiques, sécurité et exploitation.

Découvrir nos offres d’observabilité

Échanger avec ADN Consulting

Pour aller plus loin