Grafana : rendre un dashboard dynamique avec les variables

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

• 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.
• Injecter la variable dans une requête PromQL avec =~.
• Ajouter une variable Interval pour la fenêtre de rate().

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

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.

1. Type : Query, Data source : Prometheus.

2. Name : handler (le nom utilisé dans les requêtes), Label : Handler (le texte du menu).

3. Query : la requête qui peuple le menu.

   label_values(prometheus_http_requests_total, handler)

4. 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 »

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

La variable existe, mais un panel ne l'utilise pas tant qu'on ne l'a pas intégrée à sa requête (la création d'un panel est détaillée dans panels et visualisations). 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. Deux notations de substitution coexistent, avec un comportement particulier en multi-valeurs :

• $handler : la valeur simple, la plus courante.
• ${handler} : identique, utile quand la variable est collée à du texte (${handler}_total).
• Avec multi-valeurs : $handler devient une regex a|b|c, d'où le =~.

Vérifier les labels avant de créer la variable

Un label n'existe que s'il est présent sur la métrique. Avant de créer la variable, listez les valeurs dans Explore :

count by (handler) (prometheus_http_requests_total)

Si le résultat est vide, le label n'existe pas sous ce nom : essayez job, instance, ou un autre label.

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.

1. Type : Interval, Name : interval.

2. Values : 1m,5m,15m,30m,1h.

3. 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 conçue pour rate() et increase(). Elle vaut max($__interval + scrape_interval, 4 * scrape_interval), où scrape_interval est la fréquence de collecte de la métrique par Prometheus. Il vient du réglage Min step de la requête, à défaut de l'intervalle de scrape de la datasource, et $__interval découle de la période affichée et de la largeur du panel. La fenêtre couvre ainsi toujours au moins quatre échantillons de scrape.

À retenir

1. Une variable filtre tous les panels d'un dashboard depuis un menu déroulant.
2. Le type Query + label_values peuple le menu à partir des labels de la datasource.
3. Multi-value + All (.*) permettent de sélectionner plusieurs valeurs ou tout.
4. On utilise =~ et $variable dans les requêtes, car le multi-valeurs produit une regex.
5. La variable Interval (ou $__rate_interval) ajuste la fenêtre de rate() sans éditer les panels.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

FAQ : questions fréquentes

À quoi sert une variable de dashboard Grafana ?

Comment peupler une variable Grafana avec Prometheus ?

Pourquoi utiliser =~ avec une variable Grafana ?

Comment changer la fenêtre de rate() depuis le dashboard ?

×

📖 Voir la documentation →