RousselTMLEARNING

Observabilité

Variables de section Grafana : des variables propres à une ligne ou à un onglet

Variables de section dans Grafana 13 : filtrer chaque ligne ou onglet d'un dashboard indépendamment, activation, création pas à pas, ordre de résolution, répétitions, limites et bonnes pratiques.

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 #

Dashboard avec une variable instance propre à chaque ligne
La ligne API Gateway et la ligne Base de données filtrent chacune leurs instances.

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 ? #

Portées des variables Grafana

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:latest
Bonne 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 #

  1. Ouvrez le dashboard et passez en mode édition.
  2. Créez si besoin une ligne ou un onglet regroupant les panneaux d'un même service, puis sélectionnez-le.
  3. Dans le panneau latéral de configuration du regroupement, ouvrez la rubrique Variables (« variables qui ne s'appliquent qu'aux panneaux du regroupement »).
  4. Ajoutez une variable : même formulaire que pour une variable de dashboard (type, nom, requête, valeurs multiples, option « All »).
  5. 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 #

Ordre de résolution des variables

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 #

NiveauNomRequête (Prometheus)
Dashboardenvlabel_values(up, env)
Ligne « API Gateway »instancelabel_values(up{job="api-gateway", env="$env"}, instance)
Ligne « Base de données »instancelabel_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.
BesoinOutil
Un filtre pour tout le dashboardVariable de dashboard
Un filtre pour une partie du dashboardVariable de section (ligne ou onglet)
Le même filtre dans plusieurs dashboardsVariable partagée (cross-dashboard)
Les mêmes panneaux pour chaque valeurLigne ou onglet répété

À vous de jouer #

  1. Dans Grafana 13, créez un dashboard avec une variable de dashboard job.
  2. Ajoutez deux lignes, « Prometheus » et « Node exporter », avec chacune une variable de section instance listant uniquement les instances de son job.
  3. Ajoutez dans chaque ligne un panneau up{instance=~"$instance"} et vérifiez que changer l'instance d'une ligne ne modifie pas l'autre.
  4. Convertissez la première ligne en onglet : la variable doit être conservée.

Sources #

Articles liés

Administration et sécurité de Grafana : organisations, équipes, RBAC, comptes de service et authentification

Administrer Grafana en entreprise : organisations, équipes, dossiers, rôles et RBAC, permissions des sources …

Dashboard engineering : visualisations d'état, annotations, panneaux de bibliothèque et navigation

Concevoir des dashboards professionnels : State timeline, Status history, Node graph, annotations, panneaux d…

Automatiser Grafana : API HTTP, Terraform et cycle de vie des dashboards

Industrialiser Grafana : API HTTP (dossiers, dashboards, utilisateurs, sources), fournisseur Terraform, dashb…

Pour aller plus loin

Soutenir

♥ SOUTENIR

Soutenez RousselTM Learning

Les formations, articles, TP et attestations restent gratuits et sans publicité intrusive. Une contribution libre, du montant de votre choix, finance l’hébergement, les environnements de TP et l’écriture de nouveaux contenus.

Contribuer avec PayPal Montant libre · carte bancaire ou compte PayPalEn savoir plus
QR code PayPal
Ou scannez ce QR code avec votre téléphone

Merci, chaque contribution compte !