Les variables Grafana transforment un dashboard figé en tableau de bord réutilisable : un menu déroulant filtre tous les panels à la fois. Au lieu de dupliquer un dashboard par service ou par environnement, on ajoute une variable et on choisit sa valeur au sommet de la page.
Ce guide de référence complète le guide Grafana. Il s'adresse aux profils débutants et intermédiaires. Vous allez créer une variable de type Query avec label_values, la rendre multi-valeurs avec une option All, l'utiliser dans vos requêtes, et ajouter une variable Interval pour ajuster la granularité.
Ce que vous allez apprendre
Section intitulée « Ce que vous allez apprendre »- Créer une variable de dashboard de type Query.
- Peupler un menu déroulant avec
label_values. - Activer le multi-valeurs et l'option All.
- Utiliser la variable dans une requête PromQL avec
=~. - Ajouter une variable Interval pour la fenêtre de
rate().
Pourquoi des variables
Section intitulée « Pourquoi des variables »Un bon dashboard répond à une question pour n'importe quel service, pas pour un seul. Sans variable, on fige service="checkout" dans chaque panel, et il faut recréer le dashboard pour un autre service. Une variable service ajoute un menu déroulant qui filtre l'ensemble des panels d'un clic. C'est ce qui rend un tableau de bord générique et partageable.
Grafana propose plusieurs types de variables ; les deux plus utiles sont Query (les valeurs viennent d'une requête à la datasource) et Interval (une liste de durées).
Créer une variable Query avec label_values
Section intitulée « Créer une variable Query avec label_values »Une variable Query interroge la datasource pour lister des valeurs. Sur Prometheus, la fonction label_values extrait toutes les valeurs uniques d'un label. On accède aux variables via les paramètres du dashboard (icône engrenage), section Variables → Add variable.
-
Type :
Query, Data source : Prometheus. -
Name :
handler(le nom utilisé dans les requêtes), Label :Handler(le texte du menu). -
Query : la requête qui peuple le menu.
label_values(prometheus_http_requests_total, handler) -
Apply : en bas, Grafana affiche les valeurs découvertes (les endpoints de l'API Prometheus).
La requête label_values(métrique, label) est la forme la plus courante. On peut aussi la restreindre : label_values(up{job="prometheus"}, instance) ne liste que les instances du job prometheus.
Multi-valeurs et option « All »
Section intitulée « Multi-valeurs et option « All » »Deux options rendent la variable bien plus pratique.
- Multi-value : autorise la sélection de plusieurs valeurs à la fois. Le menu devient une liste à cocher.
- Include All option : ajoute une entrée All qui sélectionne tout. On règle la Custom all value sur
.*, une expression régulière qui correspond à toutes les valeurs.
Quand la variable est multi-valeurs, Grafana la substitue sous forme d'alternative régulière : frontend|checkout|cart. C'est pourquoi on l'emploie avec l'opérateur =~ (match regex) et non = (égalité stricte).
Utiliser la variable dans un panel
Section intitulée « Utiliser la variable dans un panel »La variable existe, mais un panel ne l'utilise pas tant qu'on ne l'a pas intégrée à sa requête. On édite le panel et on ajoute le filtre label=~"$variable" :
sum by (handler) (rate(prometheus_http_requests_total{handler=~"$handler"}[5m]))Désormais, changer le menu Handler refiltre le panel instantanément. Trois notations de substitution coexistent :
$handler: la valeur simple, la plus courante.${handler}: identique, utile quand la variable est collée à du texte (${handler}_total).- Avec multi-valeurs :
$handlerdevient une regexa|b|c, d'où le=~.
La variable Interval
Section intitulée « La variable Interval »La variable Interval ne vient pas d'une requête : c'est une liste de durées. Elle sert à ajuster la fenêtre de rate() depuis le dashboard, pour zoomer ou lisser les courbes.
-
Type :
Interval, Name :interval. -
Values :
1m,5m,15m,30m,1h. -
Cochez Auto option pour une valeur qui s'adapte au time range affiché.
Dans les requêtes, on remplace la fenêtre fixe [5m] par [$interval] :
rate(prometheus_http_requests_total{handler=~"$handler"}[$interval])Le lecteur choisit alors la granularité sans éditer le panel. Pour un dashboard générique, on privilégie même $__rate_interval, une variable interne de Grafana qui s'ajuste automatiquement au pas de scrape et au time range.
FAQ : questions fréquentes
Section intitulée « FAQ : questions fréquentes »service="checkout" dans chaque requête, on choisit le service au moment de consulter le dashboard.label_values(métrique, label) qui liste toutes les valeurs uniques d'un label. Par exemple label_values(prometheus_http_requests_total, handler). On peut restreindre la métrique pour cibler un sous-ensemble.frontend|checkout|cart). L'opérateur =~ (match regex) accepte cette syntaxe, alors que = (égalité stricte) ne fonctionnerait que pour une valeur unique. On écrit donc {label=~"$variable"}.1m,5m,15m,30m,1h), puis en remplaçant la fenêtre fixe [5m] par [$interval] dans les requêtes. Mieux encore, la variable interne $__rate_interval s'ajuste automatiquement au pas de scrape et au time range affiché.À retenir
Section intitulée « À retenir »- Une variable filtre tous les panels d'un dashboard depuis un menu déroulant.
- Le type Query +
label_valuespeuple le menu à partir des labels de la datasource. - Multi-value + All (
.*) permettent de sélectionner plusieurs valeurs ou tout. - On utilise
=~et$variabledans les requêtes, car le multi-valeurs produit une regex. - La variable Interval (ou
$__rate_interval) ajuste la fenêtre derate()sans éditer les panels.