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.
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.
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
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
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.
É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.
- Vérifier les noms et labels de http_requests_total et http_request_duration_seconds_bucket, ou leurs équivalents.
- Identifier le service, les codes d'erreur et la fenêtre d'observation pertinentes.
À 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.
É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.
- 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.
- 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.
- 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.
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]))À 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.
ÉTAPE 3 / 4
Calculer un percentile à partir des buckets
histogram_quantile() ne s'applique pas directement à une simple moyenne.
- Agréger les buckets par le et, si nécessaire, par service avant d'appeler histogram_quantile(0.95,...).
- Vérifier l'unité de la métrique de durée et vérifier qu'un bucket +Inf est présent.
- 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.
histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket{job="app-lab"}[5m])))À 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.
É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.
- 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.
À 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.
05 · RECETTE
Comment vérifier que tout fonctionne ?
Le débit est exprimé en requêtes/s et le ratio d'erreurs conserve un dénominateur explicite.
Le p95 estimé est interprété dans la bonne unité et sur le bon service.
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
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