Déclaration des variables

Méta : grafana prometheus variables zettelkasten

📝 Déclaration des Variables Grafana (Source : Prometheus)

Pour rendre vos Grafana Dashboards interactifs, les variables (templates) se déclarent directement dans les paramètres du tableau de bord. Elles permettent d’extraire dynamiquement des listes de valeurs (labels, instances, plages de temps) depuis votre source de données (souvent en s’appuyant sur des requêtes PromQL Basics).

Une fois ces variables paramétrées et nettoyées via cet écran de déclaration, vous pourrez passer à la phase d’Utilisation des variables Grafana pour les injecter concrètement dans vos requêtes de panels.

1. Types de Variables disponibles

Lors de la création d’une variable, le choix du type définit comment sa liste de valeurs sera générée :

• Query : Interroge la base de données (Prometheus) pour récupérer une liste dynamique de labels. (Le type le plus utilisé).

• Custom : Liste statique définie manuellement.

  • Usage simple (Valeurs séparées par des virgules) : prod, staging, dev

  • Usage avancé (Paires Label/Valeur) : Permet d’afficher un nom lisible tout en interrogeant une valeur technique. Syntaxe (Espaces obligatoires) : Label : Valeur.

  • Exemple : Production : prod-cluster-01, Staging : stg-cluster-02. (L’utilisateur sélectionne “Production”, la requête utilise “prod-cluster-01”. Pour forcer l’affichage du label dans un titre de panel, on utilisera ${nom_variable:text}).

• Interval : Définit des plages de temps d’agrégation statiques (ex: 1m, 5m, 1h). Utile pour paramétrer dynamiquement les fonctions rate() de Prometheus.

• Text box : Champ de saisie libre pour l’utilisateur.

• Ad hoc : Crée un filtre clé/valeur global qui s’appliquera automatiquement à toutes les requêtes du dashboard sans configuration supplémentaire.

2. Déclaration par Requête (Type “Query”)

Pour extraire des données de Prometheus lors de la déclaration, on utilise des fonctions spécifiques dans le champ Query :

• Extraction simple (Labels) :

  • Syntaxe : label_values(nom_de_la_metrique, nom_du_label)

  • Exemple : label_values(up, instance) → Liste toutes les instances connues de la métrique up.

• Extraction avancée (Par valeur de métrique) :

  • Si on a besoin de filtrer les résultats (ex: lister uniquement les instances où le CPU > 80%), on utilise query_result().

  • Exemple : query_result(avg by (instance) (rate(node_cpu_seconds_total[5m])) > 0.8)

  • Attention : Cette fonction renvoie la requête entière. Il faut utiliser une Regex d’extraction (voir point 4) pour isoler la valeur souhaitée.

3. Options de Configuration

Paramètres de Rafraîchissement (Refresh)

Définit à quel moment Grafana relance la requête pour mettre à jour la liste des valeurs :

• On Dashboard Load : Recommandé pour la majorité des variables (pods, serveurs, namespaces).

• On Time Range Change : À utiliser si les valeurs de la variable dépendent de la plage de temps sélectionnée (ex: des instances éphémères qui n’existent que sur certaines périodes).

Options Multi-sélection et “All”

• Multi-value : Permet à l’utilisateur de sélectionner plusieurs valeurs.

• Include All option : Ajoute un choix “All” dans le menu déroulant.

  • Bonne pratique : Si vos requêtes sont complexes, définissez la valeur personnalisée (Custom all value) de “All” sur la regex .* (qui signifie “tout” en RE2) plutôt que de laisser Grafana générer une chaîne géante (val1|val2|val3).

4. Le Filtrage et l’Extraction par Regex

Dans l’écran de déclaration d’une variable, le champ “Regex” (moteur RE2) a deux fonctions principales : Filtrer (exclure des valeurs de la liste) ou Extraire (modifier ce qui est affiché dans le menu via les groupes de capture).

Syntaxe	Action sur la variable	Exemple (Champ Regex)	Input (Valeur brute)	Résultat (Dans le menu déroulant)
^ / $	Filtrer (Garder une valeur exacte)	/^web$/	web, web-1	web (web-1 est exclu de la liste)
.*	Filtrer (Préfixe/Suffixe)	/^prod-.*/	prod-api, dev-api	prod-api (dev-api est exclu)
|	Filtrer (Choix multiples)	/^(api|db).*/	api-1, db-2, web-1	api-1, db-2
\d	Filtrer (Format spécifique)	/^node-\d+$/	node-5, node-test	node-5
( )	Extraire (Modifier l’affichage)	/^srv-([a-z]+)-01$/	srv-paris-01	paris (Grafana isole la capture)
(?: )	Regrouper sans extraire	/^(?:api|db)-(\d+)$/	api-1, db-2	1, 2 (Ignore le 1er groupe)

⚠️ Règle d’or de la déclaration (Groupes de capture) :

Dès que vous utilisez une paire de parenthèses (), Grafana arrête de renvoyer la ligne complète et ne renvoie que ce qui est capturé à l’intérieur. Si vous voulez juste filtrer avec un “OU” sans couper votre texte, utilisez impérativement le groupe non-capturant (?: ).

5. Dépendances : Le Chaînage de Variables

Il est possible de déclarer une variable dont la liste dépend de la sélection d’une variable précédente, créant ainsi une hiérarchie (ex: Cluster → Namespace → Pod).

• Comment faire ? Il suffit d’inclure la variable parente (ex: $namespace) dans la requête de déclaration de la variable enfant.

• Exemple pour la déclaration de la variable $pod :

  label_values(kube_pod_info{namespace="$namespace"}, pod)

• Résultat : Dès que l’utilisateur change le namespace, la liste des pods disponibles est recalculée automatiquement.