Modèles et variables

Cette rubrique de documentation est conçue pour les espaces de travail Grafana qui prennent en charge la version 8.x de Grafana.

Pour les espaces de travail Grafana compatibles avec la version 10.x de Grafana, voir. Travailler dans la version 10 de Grafana

Pour les espaces de travail Grafana compatibles avec la version 9.x de Grafana, voir. Travailler dans la version 9 de Grafana

Une variable est un espace réservé pour une valeur. Vous pouvez utiliser des variables dans les requêtes métriques et dans les titres des panneaux. Les variables vous permettent de créer des tableaux de bord plus interactifs et dynamiques. Au lieu de coder en dur des éléments tels que les noms des serveurs, des applications et des capteurs dans vos requêtes métriques, vous pouvez utiliser des variables à leur place.

Les variables sont affichées sous forme de listes déroulantes en haut du tableau de bord. Lorsque vous modifiez la valeur à l'aide de la liste déroulante en haut du tableau de bord, les requêtes métriques de votre panneau reflètent la nouvelle valeur.

Elles peuvent être particulièrement utiles pour les administrateurs qui souhaitent permettre aux utilisateurs d'ajuster rapidement les visualisations, mais qui ne souhaitent pas leur accorder des autorisations de modification complètes. Les visualiseurs de Grafana peuvent utiliser des variables.

En utilisant des variables et des modèles, vous pouvez créer des tableaux de bord à source unique. Si vous disposez de plusieurs sources de données ou serveurs identiques, vous pouvez créer un tableau de bord unique et utiliser des variables pour modifier ce que vous visualisez. Cela simplifie la maintenance et l'entretien.

Pour obtenir la liste des types de variables pris en charge et les instructions pour ajouter chaque type de variable, voir Types de variables

Modèles

Un modèle est une requête contenant une variable.

Par exemple, si vous administriez un tableau de bord pour surveiller plusieurs serveurs, vous pourriez créer un tableau de bord pour chaque serveur. Vous pouvez également créer un tableau de bord et utiliser des panneaux contenant des modèles de requêtes, comme illustré dans l'exemple suivant.

wmi_system_threads{instance=~"$server"}

Les valeurs des variables sont toujours synchronisées avec l'URL à l'aide de la syntaxevar-<varname>=value.

Bonnes pratiques variables

Les listes déroulantes de variables sont affichées dans l'ordre dans lequel elles sont répertoriées dans la liste des variables dans les paramètres du tableau de bord.

Placez les variables que vous allez souvent modifier en haut, afin qu'elles apparaissent en premier, à l'extrême gauche du tableau de bord.

Syntaxe variable

Les titres des panneaux et les requêtes métriques peuvent voir les variables à l'aide de deux syntaxes différentes :

• $varnameCette syntaxe est plus facile à lire, comme dans l'exemple suivant : apps.frontend.$server.requests.count Cependant, vous ne pouvez pas utiliser de variable au milieu d'un mot.

• ${var_name}Utilisez cette syntaxe lorsque vous souhaitez interpoler une variable au milieu d'une expression.

• ${var_name:<format>}Ce format vous permet de mieux contrôler la façon dont Grafana interpole les valeurs. Pour plus d’informations, consultez Options avancées de format variable.

Avant que les requêtes ne soient envoyées à votre source de données, elles sont interpolées, ce qui signifie que la variable est remplacée par sa valeur actuelle. Pendant l'interpolation, la valeur de la variable peut être évitée pour se conformer à la syntaxe du langage de requête et à l'endroit où elle est utilisée. Par exemple, une variable utilisée dans une expression régulière d'une requête Prometheus sera échappée à une expression régulière. Consultez la rubrique de documentation spécifique à la source de données pour plus de détails sur l'échappement de valeur lors de l'interpolation.

Pour plus d'informations sur la syntaxe avancée permettant de remplacer le formatage par défaut de la source de données, consultezOptions avancées de format variable.

Autres options variables

Cette section explique les autres options de variables disponibles.

Saisie des options de sélection des variables

Vous pouvez utiliser les options de sélection pour gérer les sélections d'options variables. Toutes les options de sélection sont facultatives et sont désactivées par défaut.

Valeurs multiples

Si vous activez cette option, la liste déroulante des variables permet de sélectionner plusieurs options en même temps. Pour plus d’informations, consultez Formatage de variables à valeurs multiples.

Option Tout inclure

L'espace de travail Grafana ajoute une All option à la liste déroulante des variables. Si un utilisateur final sélectionne cette option, toutes les options variables sont sélectionnées.

Toutes les valeurs personnalisées

Cette option n'est visible que si l'option Tout inclure est sélectionnée.

Pour définir la valeur de l'Alloption, entrez la syntaxe regex, glob ou Lucene dans le champ Personnaliser toutes les valeurs.

Par défaut, la All valeur inclut toutes les options de l'expression combinée. Cela peut devenir très long et entraîner des problèmes de performance. Parfois, il peut être préférable de spécifier une valeur complète personnalisée, comme une expression régulière joker.

Lorsque vous utilisez une syntaxe regex, glob ou Lucene personnalisée dans l'option Personnaliser toutes les valeurs, elle n'est jamais évitée. Vous devez donc déterminer quelle est une valeur valide pour votre source de données.

Options avancées de format variable

Le formatage de l'interpolation variable dépend de la source de données, mais dans certains cas, vous souhaiterez peut-être modifier le formatage par défaut.

Par exemple, la source de données MySQL par défaut consiste à joindre plusieurs valeurs séparées par des virgules par des guillemets :. 'server01','server02' Dans certains cas, vous souhaiterez peut-être avoir une chaîne séparée par des virgules sans guillemets :. server01,server02 Pour ce faire, utilisez les options avancées de mise en forme des variables suivantes.

Syntaxe générale

Syntaxe : ${var_name:option}

Si une option de mise en forme non valide est spécifiée, glob c'est l'option par défaut, ou option de secours.

CSV

Formate les variables comportant plusieurs valeurs sous forme de chaîne séparée par des virgules.

servers = ['test1', 'test2']
String to interpolate: '${servers:csv}'
Interpolation result: 'test1,test2'

Distribué - OpenTSDB

Formate les variables avec plusieurs valeurs dans un format personnalisé pour OpenTSDB.

servers = ['test1', 'test2']
String to interpolate: '${servers:distributed}'
Interpolation result: 'test1,servers=test2'

Devis double

Formate les variables à valeur unique et à valeurs multiples dans une chaîne séparée par des virgules, exclut chaque valeur par et " met chaque valeur entre \" guillemets avec. "

servers = ['test1', 'test2']
String to interpolate: '${servers:doublequote}'
Interpolation result: '"test1","test2"'

Globe - Graphite

Formate les variables comportant plusieurs valeurs dans un glob (pour les requêtes Graphite).

servers = ['test1', 'test2']
String to interpolate: '${servers:glob}'
Interpolation result: '{test1,test2}'

JSON

Formate les variables comportant plusieurs valeurs sous forme de chaîne séparée par des virgules.

servers = ['test1', 'test2']
String to interpolate: '${servers:json}'
Interpolation result: '["test1", "test2"]'

Lucène - OpenSearch

Formate les variables avec plusieurs valeurs au format Lucene pour. OpenSearch

servers = ['test1', 'test2']
String to interpolate: '${servers:lucene}'
Interpolation result: '("test1" OR "test2")'

Code en pourcentage

Formate les variables à valeur unique et à valeurs multiples à utiliser dans les paramètres d'URL.

servers = ['foo()bar BAZ', 'test2']
String to interpolate: '${servers:percentencode}'
Interpolation result: 'foo%28%29bar%20BAZ%2Ctest2'

Barre verticale

Formate les variables comportant plusieurs valeurs dans une chaîne séparée par des tubes.

servers = ['test1.', 'test2']
String to interpolate: '${servers:pipe}'
Interpolation result: 'test1.|test2'

Raw

Désactive le formatage spécifique à la source de données, tel que les guillemets simples dans une requête SQL.

servers = ['test1.', 'test2']
String to interpolate: '${var_name:raw}'
Interpolation result: '{test.1,test2}'

Regex

Formate les variables comportant plusieurs valeurs dans une chaîne regex.

servers = ['test1.', 'test2']
String to interpolate: '${servers:regex}'
Interpolation result: '(test1\.|test2)'

Devis unique

Formate les variables à valeur unique ou multiple dans une chaîne séparée par des virgules, saisit chaque valeur par \' et ' met chaque valeur entre guillemets avec. '

servers = ['test1', 'test2']
String to interpolate: '${servers:singlequote}'
Interpolation result: "'test1','test2'"

Chaîne SQL

Formate les variables à valeur unique ou multiple dans une chaîne séparée par des virgules, saisit chaque valeur par '' et ' met chaque valeur entre guillemets avec. '

servers = ["test'1", "test2"]
String to interpolate: '${servers:sqlstring}'
Interpolation result: "'test''1','test2'"

Texte

Formate les variables à valeur unique et à valeurs multiples dans leur représentation textuelle. Pour une seule variable, elle renverra simplement la représentation textuelle. Pour les variables à valeurs multiples, elle renverra la représentation textuelle combinée avec+.

servers = ["test1", "test2"]
String to interpolate: '${servers:text}'
Interpolation result: "test1 + test2"

Formatage de variables à valeurs multiples

L'interpolation d'une variable avec plusieurs valeurs sélectionnées est délicate car il n'est pas simple de formater les multiples valeurs dans une chaîne valide dans le contexte donné dans lequel la variable est utilisée. Grafana essaie de résoudre ce problème en permettant à chaque plug-in de source de données d'indiquer au moteur d'interpolation de modèles le format à utiliser pour plusieurs valeurs.

Note

L'option Personnaliser toutes les valeurs de la variable doit être vide pour que Grafana puisse formater toutes les valeurs en une seule chaîne. Si vous laissez ce champ vide, le Grafana concatène (additionne) toutes les valeurs de la requête. Quelque chose commevalue1,value2,value3. Si une all valeur personnalisée est utilisée, elle sera plutôt quelque chose comme * ouall.

Variables à valeurs multiples avec une source de données Graphite

Graphite utilise des expressions globulaires. Dans ce cas, une variable comportant plusieurs valeurs serait interpolée comme {host1,host2,host3} si la valeur actuelle de la variable était host1, host2 et host3.

Variables à valeurs multiples avec une source de données Prometheus ou InfluxDB

InfluxDB et Prometheus utilisent des expressions regex, de sorte que la même variable serait interpolée comme. (host1|host2|host3) Chaque valeur serait également échappée à une regex. Dans le cas contraire, une valeur avec un caractère de contrôle regex briserait l'expression regex.

Variables à valeurs multiples avec une source de données Elastic

Amazon OpenSearch utilise la syntaxe de requête Lucene, de sorte que la même variable serait formatée comme suit. ("host1" OR "host2" OR "host3") Dans ce cas, chaque valeur doit être ignorée afin qu'elle ne contienne que des mots de contrôle Lucene et des guillemets.

Résolution des problèmes de format

L'échappement automatique et le formatage peuvent poser problème. Il peut être difficile de comprendre la logique d'un problème, en particulier pour InfluxDB et Prometheus, où l'utilisation de la syntaxe regex nécessite que la variable soit utilisée dans le contexte d'un opérateur regex.

Si vous ne voulez pas que Grafana effectue cet échappement et ce formatage automatiques des regex, vous devez effectuer l'une des opérations suivantes :

• Désactivez les options Inclure tout à valeurs multiples.

• Utilisez le [format de variable brut] ({{< relref "advanced-variable-format-options.md #raw" >}}).

Filtrer les variables avec regex

À l'aide de l'option Regex Query, vous pouvez filtrer la liste des options renvoyées par la variable query ou modifier les options renvoyées.

Cette section explique comment utiliser une expression régulière pour filtrer et modifier les valeurs de la liste déroulante des variables.

À l'aide de l'option Regex Query, vous filtrez la liste des options renvoyées par la requête Variable ou vous modifiez les options renvoyées. Pour plus d'informations, consultez la section Expressions régulières.

Exemples de filtrage dans la liste d'options suivante :

backend_01
backend_02
backend_03
backend_04

Filtrer de manière à ce que seules les options se terminant par 01 ou 02 soient renvoyées

Régex :

/.*[01|02]/

Résultat:

backend_01
backend_02

Filtrer et modifier les options à l'aide d'un groupe de capture regex pour renvoyer une partie du texte

Régex :

/.*(01|02)/

Résultat:

01
02

Filtrer et modifier - Exemple Prometheus

Liste des options :

up{instance="demo.robustperception.io:9090",job="prometheus"} 1 1521630638000
up{instance="demo.robustperception.io:9093",job="alertmanager"} 1 1521630638000
up{instance="demo.robustperception.io:9100",job="node"} 1 1521630638000

Régex :

/.*instance="([^"]*).*/

Résultat:

demo.robustperception.io:9090
demo.robustperception.io:9093
demo.robustperception.io:9100

Filtrage et modification à l'aide de textes nommés et de groupes de capture de valeurs

À l'aide de groupes de capture nommés, vous pouvez capturer des parties « texte » et « valeur » distinctes à partir des options renvoyées par la requête variable. La liste déroulante des variables peut contenir un nom convivial pour chaque valeur pouvant être sélectionnée.

Par exemple, lorsque vous interrogez la métrique node_hwmon_chip_names Prometheus, la valeur est plus conviviale chip_name que la valeur. chip Commencez par le résultat de requête variable suivant.

node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_0",chip_name="enp216s0f0np0"} 1
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_1",chip_name="enp216s0f0np1"} 1
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_2",chip_name="enp216s0f0np2"} 1
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_3",chip_name="enp216s0f0np3"} 1

Passez-le dans le Regex suivant.

/chip_name="(?<text>[^"]+)|chip="(?<value>[^"]+)/g

La liste déroulante suivante est produite.

Display Name          Value
------------          -------------------------
enp216s0f0np0         0000:d7:00_0_0000:d8:00_0
enp216s0f0np1         0000:d7:00_0_0000:d8:00_1
enp216s0f0np2         0000:d7:00_0_0000:d8:00_2
enp216s0f0np3         0000:d7:00_0_0000:d8:00_3

Remarque : seuls les noms de groupes de value capture text et de capture sont pris en charge.

Panneaux ou lignes répétitifs

Vous pouvez créer des tableaux de bord dynamiques à l'aide de variables de modèle. Toutes les variables de vos requêtes sont étendues à la valeur actuelle de la variable avant que la requête ne soit envoyée à la base de données. Avec les variables, vous pouvez réutiliser un tableau de bord unique pour tous vos services.

Les variables de modèle peuvent être très utiles pour modifier dynamiquement vos requêtes sur l'ensemble d'un tableau de bord. Si vous souhaitez que Grafana crée dynamiquement de nouveaux panneaux ou lignes en fonction des valeurs que vous avez sélectionnées, vous pouvez utiliser la fonction Répéter.

Panneaux répétitifs

Si une variable Multi-value ou des Include all value options sont activées, vous pouvez choisir un panneau et demander à Grafana de répéter ce panneau pour chaque valeur sélectionnée. Vous pouvez trouver la fonction de répétition sous l'onglet Général en mode édition du panneau.

Le direction contrôle la façon dont les panneaux sont disposés.

Si vous le souhaitezhorizontal, les panneaux sont disposés side-by-side. Grafana ajuste automatiquement la largeur de chaque panneau répété afin que toute la ligne soit remplie. À l'heure actuelle, vous ne pouvez pas mélanger d'autres panneaux d'une ligne avec un panneau répété.

Réglez Max per row cette option pour indiquer à Grafana le nombre maximum de panneaux par ligne que vous souhaitez. La valeur par défaut est 4.

Si vous le souhaitezvertical, les panneaux sont disposés de haut en bas dans une colonne. La largeur des panneaux répétés est la même que celle du premier panneau (le gabarit original) répété.

Apportez des modifications uniquement au premier panneau (le modèle d'origine). Pour que les modifications prennent effet sur tous les panneaux, vous devez lancer une refonte dynamique du tableau de bord. Vous pouvez le faire soit en modifiant la valeur de la variable (c'est-à-dire la base de la répétition), soit en rechargeant le tableau de bord.

Note

Les panneaux récurrents nécessitent des variables pour qu'un ou plusieurs éléments soient sélectionnés. Vous ne pouvez pas répéter un panneau zéro fois pour le masquer.

Lignes répétitives

Comme indiqué ci-dessus, avec les panneaux, vous pouvez également répéter des lignes si vous avez défini des variables Multi-value ou une option Include all value de sélection.

Pour activer cette fonctionnalité, vous devez d'abord ajouter une nouvelle ligne à l'aide du menu Ajouter un panneau. Faites ensuite une pause sur le titre de la ligne et cliquez sur le bouton en forme de roue dentée pour accéder au panneau Row Options de configuration. Vous pouvez ensuite sélectionner la variable pour laquelle vous souhaitez répéter la ligne.

Il est recommandé d'utiliser également une variable dans le titre de la ligne.