Vorlagen und Variablen

Dieses Dokumentationsthema wurde für Grafana-Workspaces entwickelt, die Grafana-Version 8.x unterstützen.

Informationen zu Grafana-Arbeitsbereichen, die Grafana-Version 10.x unterstützen, finden Sie unter. Arbeitet in Grafana-Version 10

Informationen zu Grafana-Arbeitsbereichen, die Grafana-Version 9.x unterstützen, finden Sie unter. Arbeitet in Grafana-Version 9

Eine Variable ist ein Platzhalter für einen Wert. Sie können Variablen in metrischen Abfragen und in Paneltiteln verwenden. Variablen bieten Ihnen die Möglichkeit, interaktivere und dynamischere Dashboards zu erstellen. Anstatt Dinge wie Server-, Anwendungs- und Sensornamen in Ihren metrischen Abfragen fest zu codieren, können Sie stattdessen Variablen verwenden.

Variablen werden als Dropdownlisten oben im Dashboard angezeigt. Wenn Sie den Wert mithilfe der Dropdownliste oben im Dashboard ändern, spiegeln die Metrikabfragen Ihres Panels den neuen Wert wider.

Diese können besonders für Administratoren nützlich sein, die es Zuschauern ermöglichen möchten, Visualisierungen schnell anzupassen, ihnen aber keine vollständigen Bearbeitungsberechtigungen geben möchten. Grafana-Zuschauer können Variablen verwenden.

Durch die Verwendung von Variablen und Vorlagen können Sie Dashboards aus einer Hand beziehen. Wenn Sie über mehrere identische Datenquellen oder Server verfügen, können Sie ein Dashboard erstellen und Variablen verwenden, um zu ändern, was Sie gerade sehen. Dies vereinfacht Wartung und Instandhaltung.

Eine Liste der unterstützten Variablentypen und Anweisungen zum Hinzufügen der einzelnen Variablentypen finden Sie unter Typen von Variablen

Vorlagen

Eine Vorlage ist jede Abfrage, die eine Variable enthält.

Wenn Sie beispielsweise ein Dashboard zur Überwachung mehrerer Server verwalten würden, könnten Sie für jeden Server ein Dashboard erstellen. Oder Sie könnten ein Dashboard erstellen und Panels mit Vorlagenabfragen verwenden, wie im folgenden Beispiel gezeigt.

wmi_system_threads{instance=~"$server"}

Variablenwerte werden immer mithilfe der Syntax var-<varname>=value mit der URL synchronisiert.

Bewährte Methoden für Variablen

Variablen-Dropdownlisten werden in der Reihenfolge angezeigt, in der sie in der Variablenliste in den Dashboard-Einstellungen aufgeführt sind.

Platzieren Sie die Variablen, die Sie häufig ändern werden, ganz oben, sodass sie zuerst angezeigt werden, ganz links im Dashboard.

Syntax der Variablen

Bei Panel-Titeln und metrischen Abfragen können Variablen mithilfe von zwei verschiedenen Syntaxen erkannt werden:

• $varnameDiese Syntax ist einfacher zu lesen, wie im folgenden Beispiel:apps.frontend.$server.requests.count. Sie können jedoch keine Variable in der Mitte eines Wortes verwenden.

• ${var_name}Verwenden Sie diese Syntax, wenn Sie eine Variable in der Mitte eines Ausdrucks interpolieren möchten.

• ${var_name:<format>}Dieses Format gibt Ihnen mehr Kontrolle darüber, wie Grafana Werte interpoliert. Weitere Informationen finden Sie unter Erweiterte Optionen für das Variablenformat.

Bevor Abfragen an Ihre Datenquelle gesendet werden, wird die Abfrage interpoliert, was bedeutet, dass die Variable durch ihren aktuellen Wert ersetzt wird. Während der Interpolation kann der Variablenwert maskiert werden, um der Syntax der Abfragesprache und dem Verwendungszweck zu entsprechen. Beispielsweise wird eine Variable, die in einem Regex-Ausdruck in einer Prometheus-Abfrage verwendet wird, mit Regex-Escapes versehen. Einzelheiten zur Umgehung von Werten bei der Interpolation finden Sie in der datenquellenspezifischen Dokumentation.

Informationen zur erweiterten Syntax zum Überschreiben der Standardformatierung von Datenquellen finden Sie unter. Erweiterte Optionen für das Variablenformat

Andere Variablenoptionen

In diesem Abschnitt werden die anderen verfügbaren Variablenoptionen erläutert.

Variablenauswahloptionen eingeben

Sie können die Auswahloptionen verwenden, um die Auswahl variabler Optionen zu verwalten. Alle Auswahloptionen sind optional und standardmäßig deaktiviert.

Mehrwertig

Wenn Sie diese Option aktivieren, unterstützt die Dropdownliste für Variablen die gleichzeitige Auswahl mehrerer Optionen. Weitere Informationen finden Sie unter Formatieren von Variablen mit mehreren Werten.

Option „Alle einbeziehen“

Der Grafana-Arbeitsbereich fügt der Variablen-Dropdownliste eine All Option hinzu. Wenn ein Endbenutzer diese Option auswählt, werden alle variablen Optionen ausgewählt.

Benutzerdefinierter Wert für alle

Diese Option ist nur sichtbar, wenn die Option Alle einbeziehen ausgewählt ist.

Um den Wert der All Option zu definieren, geben Sie Regex-, Glob- oder Lucene-Syntax in das Feld Alle Werte anpassen ein.

Standardmäßig umfasst der All Wert alle Optionen im kombinierten Ausdruck. Dies kann sehr lang werden und zu Leistungseinbußen führen. Manchmal kann es besser sein, einen benutzerdefinierten All-Wert anzugeben, z. B. einen Platzhalter-Regex.

Wenn Sie eine benutzerdefinierte Regex-, Glob- oder Lucene-Syntax in der Option Alle Werte anpassen verwenden, wird diese nie maskiert. Sie müssen also überlegen, welcher Wert für Ihre Datenquelle gültig ist.

Erweiterte Optionen für das Variablenformat

Die Formatierung der Variableninterpolation hängt von der Datenquelle ab, es gibt jedoch Situationen, in denen Sie möglicherweise die Standardformatierung ändern möchten.

Die Standardeinstellung für die MySQL-Datenquelle besteht beispielsweise darin, mehrere Werte durch Kommas getrennt durch Anführungszeichen zu verbinden:. 'server01','server02' In einigen Fällen möchten Sie vielleicht eine durch Kommas getrennte Zeichenfolge ohne Anführungszeichen verwenden:. server01,server02 Verwenden Sie dazu die folgenden erweiterten Formatierungsoptionen für Variablen.

Allgemeine Syntax

Syntax: ${var_name:option}

Wenn eine ungültige Formatierungsoption angegeben wurde, glob ist dies die Standard- oder Ausweichoption.

CSV

Formatiert Variablen mit mehreren Werten als kommagetrennte Zeichenfolge.

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

Verteilt - OpenTSDB

Formatiert Variablen mit mehreren Werten in einem benutzerdefinierten Format für OpenTSDB.

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

Doppeltes Anführungszeichen

Formatiert Variablen mit einem und mehreren Werten in eine durch Kommas getrennte Zeichenfolge, maskiert jeden Wert mit und setzt jeden Wert mit " \" in Anführungszeichen. "

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

Glob - Graphit

Formatiert Variablen mit mehreren Werten in einen Glob (für Graphite-Abfragen).

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

JSON

Formatiert Variablen mit mehreren Werten als kommagetrennte Zeichenfolge.

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

Lucene - OpenSearch

Formatiert Variablen mit mehreren Werten im Lucene-Format für. OpenSearch

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

Prozentualer Code

Formatiert Variablen mit einem und mehreren Werten zur Verwendung in URL-Parametern.

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

Pipe

Formatiert Variablen mit mehreren Werten in eine durch Leerzeichen getrennte Zeichenfolge.

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

Raw

Deaktiviert datenquellenspezifische Formatierungen, z. B. einfache Anführungszeichen in einer SQL-Abfrage.

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

Regex

Formatiert Variablen mit mehreren Werten in eine Regex-Zeichenfolge.

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

Einfaches Anführungszeichen

Formatiert Variablen mit einem und mehreren Werten in eine durch Kommas getrennte Zeichenfolge, maskiert jeden Wert mit und setzt jeden Wert mit ' in \' Anführungszeichen. '

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

SQL-String

Formatiert Variablen mit einem und mehreren Werten in eine durch Kommas getrennte Zeichenfolge, maskiert jeden Wert mit '' und setzt jeden Wert mit ' in Anführungszeichen. '

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

Text

Formatiert Variablen mit einem und mehreren Werten in ihre Textdarstellung. Für eine einzelne Variable wird nur die Textdarstellung zurückgegeben. Bei Variablen mit mehreren Werten wird die Textdarstellung in Kombination mit + zurückgegeben.

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

Formatieren von Variablen mit mehreren Werten

Das Interpolieren einer Variablen mit mehreren ausgewählten Werten ist schwierig, da es nicht einfach ist, die mehreren Werte in eine Zeichenfolge zu formatieren, die in dem angegebenen Kontext, in dem die Variable verwendet wird, gültig ist. Grafana versucht, dieses Problem zu lösen, indem es jedem Datenquellen-Plugin ermöglicht, der Templating-Interpolationsengine mitzuteilen, welches Format für mehrere Werte verwendet werden soll.

Anmerkung

Die Option Benutzerdefiniert für alle Werte für die Variable muss leer sein, damit Grafana alle Werte in einer einzigen Zeichenfolge formatieren kann. Wenn Sie das Feld leer lassen, verkettet (addiert) Grafana alle Werte in der Abfrage. Etwas wie. value1,value2,value3 Wenn ein benutzerdefinierter all Wert verwendet wird, lautet der Wert stattdessen etwa * oderall.

Variablen mit mehreren Werten und einer Graphite-Datenquelle

Graphite verwendet Glob-Ausdrücke. Eine Variable mit mehreren Werten würde in diesem Fall so interpoliert werden, als {host1,host2,host3} ob der aktuelle Variablenwert host1, host2 und host3 wäre.

Mehrwertige Variablen mit einer Prometheus- oder InfluxDB-Datenquelle

InfluxDB und Prometheus verwenden Regex-Ausdrücke, sodass dieselbe Variable interpoliert würde als. (host1|host2|host3) Jeder Wert würde auch mit Regex-Escapes versehen werden. Andernfalls würde ein Wert mit einem Regex-Steuerzeichen den Regex-Ausdruck unterbrechen.

Variablen mit mehreren Werten und einer Elastic-Datenquelle

Amazon OpenSearch verwendet die Lucene-Abfragesyntax, sodass dieselbe Variable als formatiert würde. ("host1" OR "host2" OR "host3") In diesem Fall muss jeder Wert maskiert werden, sodass der Wert nur Lucene-Steuerwörter und Anführungszeichen enthält.

Problembehandlung beim Formatieren

Automatisches Escapen und Formatieren können zu Problemen führen. Es kann schwierig sein, die Logik hinter einem Problem zu verstehen, insbesondere für InfluxDB und Prometheus, wo die Verwendung der Regex-Syntax erfordert, dass die Variable im Regex-Operator-Kontext verwendet wird.

Wenn Sie nicht möchten, dass Grafana dieses automatische Regex-Escaping und Formatieren durchführt, müssen Sie einen der folgenden Schritte ausführen:

• Deaktivieren Sie die Optionsoptionen „Alle einbeziehen“ mit mehreren Werten.

• Verwenden Sie das [unformatierte Variablenformat] ({{< relref "advanced-variable-format-options.md #raw" >}}).

Variablen mit Regex filtern

Mithilfe der Regex-Abfrageoption können Sie die Liste der von der Variablenabfrage zurückgegebenen Optionen filtern oder die zurückgegebenen Optionen ändern.

In diesem Abschnitt wird gezeigt, wie Sie Regex verwenden, um Werte in der Variablen-Dropdownliste zu filtern und zu ändern.

Mithilfe der Regex-Abfrageoption filtern Sie die Liste der von der Variablenabfrage zurückgegebenen Optionen oder ändern die zurückgegebenen Optionen. Weitere Informationen finden Sie unter Reguläre Ausdrücke.

Beispiele für das Filtern anhand der folgenden Liste von Optionen:

backend_01
backend_02
backend_03
backend_04

Filterung, sodass nur die Optionen zurückgegeben 02 werden, die mit 01 oder enden

Regex:

/.*[01|02]/

Ergebnis:

backend_01
backend_02

Filtern und Ändern der Optionen mithilfe einer Regex-Capture-Gruppe, um einen Teil des Textes zurückzugeben

Regex:

/.*(01|02)/

Ergebnis:

01
02

Filtern und Ändern - Prometheus-Beispiel

Liste der Optionen:

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

Regex:

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

Ergebnis:

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

Filtern und Ändern mithilfe von benannten Text- und Werterfassungsgruppen

Mithilfe benannter Erfassungsgruppen können Sie separate Teile von „Text“ und „Wert“ aus den von der Variablenabfrage zurückgegebenen Optionen erfassen. Die Dropdownliste für Variablen kann für jeden auswählbaren Wert einen benutzerfreundlichen Namen enthalten.

Wenn Sie beispielsweise die node_hwmon_chip_names Prometheus-Metrik abfragen, chip_name ist der freundlicher als der Wert. chip Beginnen Sie mit dem folgenden variablen Abfrageergebnis.

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

Übergeben Sie es durch den folgenden Regex.

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

Die folgende Drop-down-Liste wird erstellt.

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

Hinweis: Nur Gruppennamen text und value Capture-Namen werden unterstützt.

Wiederholte Panels oder Zeilen

Sie können dynamische Dashboards mithilfe von Vorlagenvariablen erstellen. Alle Variablen in Ihren Abfragen werden auf den aktuellen Wert der Variablen erweitert, bevor die Abfrage an die Datenbank gesendet wird. Mit Variablen können Sie ein einziges Dashboard für all Ihre Dienste wiederverwenden.

Vorlagenvariablen können sehr nützlich sein, um Ihre Abfragen in einem gesamten Dashboard dynamisch zu ändern. Wenn Sie möchten, dass Grafana dynamisch neue Panels oder Zeilen basierend auf den von Ihnen ausgewählten Werten erstellt, können Sie die Wiederholungsfunktion verwenden.

Wiederholte Panels

Wenn Sie eine Variable mit Multi-value aktivierten Include all value Optionen oder aktiviert haben, können Sie ein Panel auswählen und Grafana dieses Panel für jeden ausgewählten Wert wiederholen lassen. Sie finden die Wiederholungsfunktion auf der Registerkarte Allgemein im Panel-Bearbeitungsmodus.

Sie direction steuert, wie die Bedienfelder angeordnet sind.

Wenn Sie möchtenhorizontal, werden die Bedienfelder angeordnet side-by-side. Grafana passt die Breite jedes wiederholten Panels automatisch an, sodass die gesamte Zeile gefüllt ist. Derzeit ist es nicht möglich, andere Panels in einer Reihe mit einem sich wiederholenden Panel zu mischen.

Stellen Max per row Sie ein, dass Grafana mitteilt, wie viele Panels pro Zeile Sie maximal haben möchten. Die Standardeinstellung ist 4.

Wenn Sie wählenvertical, werden die Bereiche von oben nach unten in einer Spalte angeordnet. Die Breite der wiederholten Panels entspricht der des ersten Panels (der Originalvorlage), das wiederholt wird.

Nehmen Sie nur Änderungen am ersten Bedienfeld (der Originalvorlage) vor. Damit die Änderungen in allen Bereichen wirksam werden, müssen Sie ein dynamisches Dashboard neu erstellen. Sie können dies tun, indem Sie entweder den Variablenwert (d. h. die Grundlage für die Wiederholung) ändern oder das Dashboard neu laden.

Anmerkung

Bei wiederholten Bedienfeldern müssen für Variablen ein oder mehrere Elemente ausgewählt sein. Sie können ein Panel nicht null Mal wiederholen, um es auszublenden.

Zeilen wiederholen

Wie oben bei den Panels gezeigt, können Sie Zeilen auch wiederholen, wenn Sie Variablen mit Multi-value oder eine Include all value Auswahloption gesetzt haben.

Um diese Funktion zu aktivieren, müssen Sie zunächst über das Menü „Bereich hinzufügen“ eine neue Zeile hinzufügen. Halten Sie dann beim Zeilentitel inne und wählen Sie die Zahnradtaste, um das Row Options Konfigurationsfenster aufzurufen. Sie können dann die Variable auswählen, für die Sie die Zeile wiederholen möchten.

Es hat sich bewährt, eine Variable auch im Zeilentitel zu verwenden.