1. Le problème des variables globales au dashboard #
Une variable de dashboard filtre tous les panneaux à la fois.
Un seul filtre pour tout le dashboard #
Disponible dans : ✓ OSS ✓ Enterprise ✓ Cloud Disponibilité générale depuis juin 2026 (Grafana 13, dashboards dynamiques)
Jusqu'ici, une variable comme $instance appartenait au dashboard entier : changer sa valeur modifiait tous les panneaux. Or un même dashboard regroupe souvent des services différents, par exemple une passerelle d'API et une base de données, dont les instances n'ont rien en commun. Choisir gw-01 vidait alors les panneaux de la base de données, et inversement.
Les contournements habituels #
- Découper en plusieurs dashboards : chacun a ses filtres, mais on perd la vue d'ensemble et la corrélation sur une même période.
- Multiplier les variables (
$gw_instance,$db_instance…) : la barre de variables s'allonge et l'on ne sait plus quel filtre agit sur quel panneau. - Répéter une ligne par valeur : utile pour comparer des valeurs, pas pour filtrer différemment deux services.
2. Ce qu'apportent les variables de section #
Chaque ligne ou onglet peut avoir ses propres variables.
Le principe #
Une variable de section est définie sur une ligne ou un onglet du dashboard et ne s'applique qu'aux panneaux de ce regroupement. Les autres sections ne sont pas touchées, et toutes continuent de partager la même période de temps.
Calendrier et prérequis #
- Avril 2026 : préversion publique, dans le cadre des dashboards dynamiques de Grafana 13.
- Juin 2026 : disponibilité générale.
- Les lignes et onglets sont ceux des dashboards dynamiques (schéma de dashboard v2, format par défaut de Grafana 13) : un dashboard est migré vers ce format à son ouverture.
- Rien ne change pour les dashboards existants tant qu'on n'ajoute pas de variable à une ligne ou à un onglet.
Où se situe-t-elle ? #
Les variables de section complètent les variables de dashboard et les variables partagées entre dashboards : plus la portée est étroite, plus la variable est proche des panneaux qu'elle filtre.
3. Activer la fonctionnalité #
Grafana Cloud et Grafana auto-hébergé.
Grafana Cloud #
La fonctionnalité a été déployée progressivement sur les instances Grafana Cloud : si l'option Variables n'apparaît pas encore dans la configuration d'une ligne, elle arrivera sans action de votre part.
Grafana auto-hébergé (OSS et Enterprise) #
Utilisez Grafana 13. Si l'option n'apparaît pas dans votre version, activez le feature toggle dashboardSectionVariables, puis redémarrez Grafana :
# grafana.ini (Grafana auto-hébergé)
[feature_toggles]
enable = dashboardSectionVariables# Docker : même réglage par variable d'environnement
docker run -d -p 3000:3000 \
-e GF_FEATURE_TOGGLES_ENABLE=dashboardSectionVariables \
grafana/grafana:latestBonne Pratique : Vérifiez l'état des fonctionnalités dans Administration › Feature toggles (selon les versions) ou dans les journaux de démarrage de Grafana.
4. Créer une variable de section, pas à pas #
Depuis le mode édition du dashboard.
Pas à pas #
- Ouvrez le dashboard et passez en mode édition.
- Créez si besoin une ligne ou un onglet regroupant les panneaux d'un même service, puis sélectionnez-le.
- Dans le panneau latéral de configuration du regroupement, ouvrez la rubrique Variables (« variables qui ne s'appliquent qu'aux panneaux du regroupement »).
- Ajoutez une variable : même formulaire que pour une variable de dashboard (type, nom, requête, valeurs multiples, option « All »).
- Utilisez-la dans les requêtes des panneaux de la section, puis enregistrez le dashboard.
À savoir : Dans l'éditeur de requêtes, l'autocomplétion ne propose que les variables accessibles au panneau édité : celles de sa section, des sections parentes et du dashboard.
Types de variables #
Tous les types de variables sont acceptés au niveau d'une section (requête, personnalisée, intervalle, constante, zone de texte, source de données, filtres…), à une exception près : la fonction Filter and group by, encore en préversion dans Grafana 13, n'est pas prise en charge pour l'instant.
5. Ordre de résolution et priorité #
Section d'abord, dashboard ensuite.
La règle #
Un panneau résout d'abord les variables de sa section, puis celles des sections parentes (un onglet qui contient la ligne), et se rabat enfin sur les variables du dashboard.
Même nom, deux valeurs #
Conséquence directe : si une ligne définit une variable instance alors que le dashboard en a déjà une, les panneaux de la ligne utilisent celle de la ligne, et les autres panneaux celle du dashboard. Gardez donc le même nom ($instance) dans toutes les sections : les requêtes restent identiques d'un service à l'autre, seule la liste des valeurs change.
S'appuyer sur une variable du dashboard #
Une variable de section peut utiliser une variable du dashboard dans sa requête : $env reste un filtre commun, et chaque ligne propose les instances de cet environnement.
6. Exemple complet : passerelle d'API et base de données #
Un dashboard, deux services, deux listes d'instances.
Les variables #
| Niveau | Nom | Requête (Prometheus) |
|---|---|---|
| Dashboard | env | label_values(up, env) |
| Ligne « API Gateway » | instance | label_values(up{job="api-gateway", env="$env"}, instance) |
| Ligne « Base de données » | instance | label_values(pg_up{env="$env"}, instance) |
Les panneaux #
Dans la ligne API Gateway :
sum by (instance) (rate(http_requests_total{job="api-gateway", env="$env", instance=~"$instance"}[5m]))Dans la ligne Base de données :
sum by (instance) (pg_stat_activity_count{env="$env", instance=~"$instance"})Les deux requêtes utilisent $instance, mais chaque ligne lui donne sa propre valeur. Changer l'instance de la passerelle ne touche pas aux panneaux de la base de données, et changer $env met à jour les deux lignes.
7. Lignes, onglets, répétitions et imbrication #
Les variables suivent la structure du dashboard.
Ce qui est conservé #
- Convertir une ligne en onglet (ou l'inverse), ou changer de disposition, conserve les variables de la section.
- Les variables de section fonctionnent avec les lignes et onglets répétés : chaque copie garde les filtres de la section.
- Dissoudre un regroupement ne supprime pas ses variables : elles remontent au niveau supérieur.
- Les regroupements s'imbriquent jusqu'à quatre niveaux (des onglets contenant des lignes, par exemple), chacun pouvant avoir ses variables.
Répétition ou variable de section ? #
Une ligne répétée duplique les mêmes panneaux pour chaque valeur d'une variable (une ligne par région, par exemple) : c'est l'outil de la comparaison. Une variable de section filtre une partie du dashboard sans rien dupliquer : c'est l'outil des services différents réunis dans un même dashboard.
8. Limites, bonnes pratiques et exercice #
À retenir avant de restructurer vos dashboards.
Limites #
- La période de temps reste commune à tout le dashboard : une section ne peut pas avoir sa propre plage horaire.
- Filter and group by (préversion de Grafana 13) n'est pas encore disponible au niveau d'une section.
- Les lignes et onglets sont ceux des dashboards dynamiques : un dashboard resté au format classique doit d'abord être ouvert et enregistré dans Grafana 13.
Bonnes pratiques #
- Placez au niveau du dashboard les filtres réellement communs (
$env,$cluster) et au niveau de la section ceux qui dépendent du service. - Gardez des noms identiques d'une section à l'autre pour réutiliser les mêmes requêtes.
- Avec Git Sync ou le provisioning, les variables de section sont enregistrées dans le JSON du dashboard : relisez-les en revue de code comme le reste.
- Pour un filtre utile à plusieurs dashboards, préférez une variable partagée entre dashboards.
| Besoin | Outil |
|---|---|
| Un filtre pour tout le dashboard | Variable de dashboard |
| Un filtre pour une partie du dashboard | Variable de section (ligne ou onglet) |
| Le même filtre dans plusieurs dashboards | Variable partagée (cross-dashboard) |
| Les mêmes panneaux pour chaque valeur | Ligne ou onglet répété |
À vous de jouer #
- Dans Grafana 13, créez un dashboard avec une variable de dashboard
job. - Ajoutez deux lignes, « Prometheus » et « Node exporter », avec chacune une variable de section
instancelistant uniquement les instances de son job. - Ajoutez dans chaque ligne un panneau
up{instance=~"$instance"}et vérifiez que changer l'instance d'une ligne ne modifie pas l'autre. - Convertissez la première ligne en onglet : la variable doit être conservée.
