Utilisation des variables

Méta : grafana prometheus promql variables zettelkasten

Note mère : Grafana Dashboards

📝 Utilisation des Variables Grafana (Requêtes PromQL & Panels)

Une fois que vous avez configuré et testé vos templates via la Déclaration des Variables Grafana, il faut maintenant les injecter dans les requêtes de vos panels ou dans la configuration de votre tableau de bord pour rendre l’affichage dynamique et interactif pour l’utilisateur.

1. Syntaxe d’Injection de Base

Pour appeler une variable dans un champ de texte (comme le titre d’un graphique) ou dans une requête, on utilise le symbole $.

• Syntaxe standard : $nom_variable (Ex: up{instance="$server"})

• Syntaxe protégée : ${nom_variable}. Fortement recommandée si la variable est collée à un autre mot, pour éviter que Grafana ne confonde le nom de la variable avec le reste du texte (Ex: rate(metric_${app}_total[5m])).

• (Obsolète : La syntaxe [[nom_variable]] existe encore pour des raisons de rétrocompatibilité, mais elle est dépréciée).

2. Règle d’Or : Les Opérateurs PromQL (=~ vs =)

C’est la source d’erreur la plus fréquente quand on applique ses PromQL Basics dans Grafana. Le choix de l’opérateur d’égalité dépend des options de votre variable (Multi-value ou Include All).

A. Variable à choix unique (Single value)

Si l’utilisateur ne peut sélectionner qu’une seule valeur dans le menu déroulant, l’opérateur d’égalité stricte de Prometheus suffit.

• Requête : node_load1{instance="$server"}

B. Variable à choix multiples (Multi-value / All)

Si l’utilisateur sélectionne plusieurs serveurs (ex: srv-1 et srv-2), Grafana va transformer la variable en une liste formatée en Regex : (srv-1|srv-2).

L’opérateur = plantera, car aucune instance dans votre base de données ne s’appelle littéralement (srv-1|srv-2).

Il faut impérativement utiliser l’opérateur Regex =~.

• Sélection (Inclusion) : node_load1{instance=~"$server"}

• Exclusion : node_load1{instance!~"$server"} (Affiche tout sauf les serveurs sélectionnés).

3. Formatage Avancé de la Sortie (Variable Formatting)

Selon la source de données (Prometheus, MySQL, InfluxDB…), vous pouvez forcer Grafana à formater la liste des valeurs sélectionnées d’une manière spécifique en utilisant la syntaxe ${variable:format}.

Syntaxe	Résultat (Si l’utilisateur sélectionne ‘A’ et ‘B’)	Cas d’usage principal
${var:regex}	(A|B)	Format par défaut pour Prometheus.
${var:pipe}	A|B	Utile pour des regex complexes sans les parenthèses encapsulantes.
${var:csv}	A,B	Indispensable pour les bases SQL : WHERE host IN (${var:csv})
${var:singlequote}	'A','B'	Requêtes SQL nécessitant des chaînes de caractères.
${var:text}	Serveur A + Serveur B	Affiche le nom lisible de la variable (son label) au lieu de sa valeur technique. Idéal pour formater proprement les titres dans Grafana Panels : Manipulation de l’Affichage et Légendes.

4. Fonctionnalité Avancée : La Répétition (Repeat)

Les variables configurées en Multi-value offrent une fonctionnalité magique : générer dynamiquement l’interface graphique en fonction des choix de l’utilisateur.

• Panel Repeat : Dans les options d’un Panel, définissez “Repeat by variable” sur votre variable $server. Si l’utilisateur sélectionne 3 serveurs, Grafana clonera automatiquement le graphique 3 fois côte à côte (un graphique distinct par serveur).

• Row Repeat : Même principe, mais appliqué à une “Ligne” (Row) entière du Dashboard. Très puissant pour créer une vue détaillée qui se duplique pour chaque cluster ou namespace sélectionné.

  • Astuce : Utilisez la syntaxe de variable dans le titre de la ligne (ex: Métrique pour le serveur $server) pour que chaque ligne générée automatiquement affiche le bon titre.