[Article] Les variables locales

2. Variables Globales vs Variables Personnalisées #

Distinguer les outils natifs de Grafana des configurations sur mesure.

Les Variables Globales (Built-in) #

Grafana propose des variables intégrées (built-in) qui sont automatiquement disponibles et utilisables partout sans configuration préalable. Elles fournissent des informations contextuelles sur le tableau de bord, l'utilisateur ou la plage horaire.

${__from} / ${__to} : Représentent le début et la fin de la plage horaire sélectionnée dans le tableau de bord, exprimés en millisecondes Unix. Utiles pour passer la plage horaire à des liens externes ou des requêtes d'API.
${__interval} : L'intervalle de temps calculé par Grafana pour regrouper les données (par exemple, '5m' pour 5 minutes). Cet intervalle est optimisé pour la résolution de votre graphique.
${__interval_ms} : L'intervalle de temps en millisecondes.
${__user.id} : L'identifiant unique de l'utilisateur actuellement connecté.
${__user.login} : Le nom d'utilisateur (login) de l'utilisateur connecté.
${__user.email} : L'adresse e-mail de l'utilisateur connecté.
${__dashboard.name} : Le nom du tableau de bord actuel.
${__dashboard.uid} : L'identifiant unique (UID) du tableau de bord actuel.
${__panel.id} : L'identifiant unique du panel actuel.
${__panel.name} : Le nom du panel actuel.
${__org.id} : L'identifiant unique de l'organisation Grafana actuelle.
${__org.name} : Le nom de l'organisation Grafana actuelle.
${__url_time_range} : La plage horaire formatée pour être utilisée dans une URL (par exemple, from=1678886400000&to=1678972800000).
${__url_variables} : Toutes les variables du tableau de bord formatées pour être utilisées dans une URL.

Les Variables Personnalisées (Custom & Query) #

Ce sont les variables que vous définissez et configurez spécifiquement pour vos tableaux de bord, offrant une flexibilité maximale pour interagir avec vos données :

Query : Le type de variable le plus puissant. Elle exécute une requête sur une source de données (par exemple, 'Lister tous les noms de serveurs depuis Prometheus' ou 'Récupérer tous les noms de pods Kubernetes') pour générer dynamiquement une liste de valeurs sélectionnables.
Custom : Permet de définir une liste de valeurs fixes, séparées par des virgules (ex: 'production, staging, development' ou 'true, false'). Utile pour des options prédéfinies qui ne changent pas fréquemment.
Datasource : Permet à l'utilisateur de changer dynamiquement la source de données utilisée par les panels du tableau de bord. Par exemple, basculer entre deux clusters Prometheus différents ou deux instances Elasticsearch.
Constant : Une variable cachée qui stocke une valeur fixe. Utile pour des paramètres qui ne doivent pas être modifiés par l'utilisateur mais qui sont utilisés dans les requêtes (ex: un préfixe de nom d'index).
Text box : Une zone de texte libre où l'utilisateur peut saisir n'importe quelle valeur.

3. Utilisation dans les Dashlets et les Titres #

Comment injecter la dynamique dans vos visualisations.

Syntaxe dans les requêtes #

Pour utiliser une variable dans une requête (PromQL, SQL, Lucene, etc.), Grafana supporte plusieurs syntaxes :

Syntaxe actuelle (recommandée) : Utilise le préfixe $ (ex: $varname) ou les accolades ${varname}. La syntaxe avec accolades est préférable car elle permet d'utiliser des modificateurs de formatage (voir section suivante).
Exemple en PromQL : node_cpu_seconds_total{instance="$instance"}.
Syntaxe dépréciée : L'ancienne syntaxe [[varname]] est toujours fonctionnelle mais est considérée comme dépréciée et ne devrait plus être utilisée dans les nouveaux tableaux de bord.

Grafana remplace la variable par la valeur sélectionnée par l'utilisateur avant d'envoyer la requête à la source de données.

Titres et Textes dynamiques #

Il est recommandé d'inclure les variables dans les titres de vos panels pour savoir ce que l'on regarde. Si votre variable $app est sur 'EasyTrade', un titre configuré comme Erreurs sur $app s'affichera Erreurs sur EasyTrade. Vous pouvez aussi utiliser ${app:text} pour afficher le label lisible ou ${app:value} pour la valeur technique.

Formats de variables pour les requêtes #

Grafana offre plusieurs options de formatage pour les variables, permettant d'adapter leur sortie au contexte de la requête de la source de données. Ces formats sont spécifiés après le nom de la variable, précédés d'un deux-points (:).

${varname:csv} : Formate la variable en une chaîne de caractères séparée par des virgules. Utile pour les clauses IN en SQL (ex: host IN ('server1', 'server2')).
${varname:doublequote} : Entoure chaque valeur d'une liste de guillemets doubles (ex: "value1","value2").
${varname:singlequote} : Entoure chaque valeur d'une liste de guillemets simples (ex: 'value1','value2').
${varname:raw} : Retourne la valeur brute de la variable, sans échappement ni formatage.
${varname:regex} : Formate la variable pour être utilisée dans une expression régulière (ex: (value1|value2)).
${varname:lucene} : Formate la variable pour les requêtes Lucene (ex: (value1 OR value2)).
${varname:percentencode} : Encode la valeur pour une utilisation dans une URL (ex: les espaces deviennent %20).
${varname:glob} : Formate la variable pour les requêtes de type glob (ex: {value1,value2}).
${varname:pipe} : Sépare les valeurs par un pipe (|).
${varname:distributed} : Formate pour les requêtes distribuées (par exemple, pour InfluxDB).