Vorlagen für Beschriftungen und Anmerkungen

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

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

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

Sie können Vorlagen verwenden, um Daten aus Abfragen und Ausdrücken in Beschriftungen und Anmerkungen aufzunehmen. Möglicherweise möchten Sie den Schweregrad für eine Warnung auf der Grundlage des Werts der Abfrage festlegen oder das Instanzlabel aus der Abfrage in einer zusammenfassenden Anmerkung verwenden, damit Sie wissen, auf welchem Server eine hohe CPU-Auslastung herrscht.

Alle Vorlagen sollten in Text/Vorlage geschrieben werden. Unabhängig davon, ob Sie eine Vorlage für ein Etikett oder eine Anmerkung erstellen, sollten Sie jede Vorlage direkt in das Etikett oder die Anmerkung schreiben, für die Sie eine Vorlage erstellen. Das bedeutet, dass Sie Vorlagen nicht gemeinsam mit Beschriftungen und Anmerkungen verwenden können. Stattdessen müssen Sie Vorlagen überall dort kopieren, wo Sie sie verwenden möchten.

Jede Vorlage wird immer dann ausgewertet, wenn die Warnungsregel ausgewertet wird, und zwar für jede Warnung separat. Wenn Ihre Warnungsregel beispielsweise eine Vorlage für eine Zusammenfassung enthält und die Warnungsregel 10 auslösende Alerts enthält, wird die Vorlage zehnmal ausgeführt, einmal für jede Warnung. Sie sollten versuchen, teure Berechnungen in Ihren Vorlagen so weit wie möglich zu vermeiden.

Beispiele

Anstatt ein vollständiges Tutorial zum Thema Text/Vorlage zu schreiben, versuchen die folgenden Beispiele, die häufigsten Anwendungsfälle aufzuzeigen, die wir für Vorlagen gesehen haben. Sie können diese Beispiele wörtlich verwenden oder sie nach Bedarf an Ihren Anwendungsfall anpassen. Weitere Informationen zum Schreiben von Text/Vorlagen finden Sie in der Text-/Vorlagendokumentation.

Alle Etiketten durch Kommas getrennt drucken

Um alle Etiketten durch Kommas getrennt zu drucken, drucken Sie die $labels Variable:

{{ $labels }}

Wenn zum Beispiel eine Warnung mit den Beschriftungen angezeigt wird alertname=High CPU usageinstance=server1, grafana_folder=CPU alerts und das würde Folgendes drucken:

alertname=High CPU usage, grafana_folder=CPU alerts, instance=server1

Anmerkung

Wenn Sie klassische Bedingungen verwenden, enthält $labels es keine Labels aus der Abfrage. Weitere Informationen finden Sie in der Variablen $labels.

Druckt alle Etiketten, eines pro Zeile

Um alle Etiketten zu drucken, eines pro Zeile, verwenden Sie a, range um über jedes Schlüssel/Wert-Paar zu iterieren und sie einzeln zu drucken. $kBezieht sich hier auf den Namen und $v bezieht sich auf den Wert des aktuellen Labels:

{{ range $k, $v := $labels -}}
{{ $k }}={{ $v }}
{{ end }}

Wenn zum Beispiel eine Warnung mit den Beschriftungen angezeigt alertname=High CPU usage wirdinstance=server1, grafana_folder=CPU alerts und das würde Folgendes ausgeben:

alertname=High CPU usage
grafana_folder=CPU alerts
instance=server1

Anmerkung

Wenn Sie klassische Bedingungen verwenden, enthält $labels es keine Labels aus der Abfrage. Weitere Informationen finden Sie in der Variablen $labels.

Drucken Sie ein einzelnes Etikett

Um ein einzelnes Etikett zu drucken, verwenden Sie die index Funktion mit der $labels Variablen:

The host {{ index $labels "instance" }} has exceeded 80% CPU usage for the last 5 minutes

Bei einer Warnung mit dem Etikett würde dies instance=server1 beispielsweise Folgendes drucken:

The host server1 has exceeded 80% CPU usage for the last 5 minutes

Anmerkung

Wenn Sie klassische Bedingungen verwenden, enthält $labels diese Option keine Labels aus der Abfrage. Weitere Informationen finden Sie in der Variablen $labels.

Gibt den Wert einer Abfrage aus

Um den Wert einer Sofortabfrage zu drucken, können Sie ihre Ref-ID mit der index Funktion und der $values Variablen drucken:

{{ index $values "A" }}

Bei einer Sofortabfrage, die beispielsweise den Wert 81.2345 zurückgibt, wird Folgendes gedruckt:

81.2345

Um den Wert einer Bereichsabfrage zu drucken, müssen Sie ihn zunächst mit einem Reduce-Ausdruck von einer Zeitreihe auf einen Instantvektor reduzieren. Anschließend können Sie das Ergebnis des Reduzierungsausdrucks drucken, indem Sie stattdessen dessen Ref-ID verwenden. Wenn der Reduce-Ausdruck beispielsweise den Durchschnitt von A verwendet und die Referenz-ID B hat, würden Sie schreiben:

{{ index $values "B" }}

Gibt den humanisierten Wert einer Abfrage aus

Um den humanisierten Wert einer Sofortabfrage zu drucken, verwenden Sie die humanize Funktion:

{{ humanize (index $values "A").Value }}

Bei einer Sofortabfrage, die beispielsweise den Wert 81.2345 zurückgibt, wird Folgendes gedruckt:

81.234

Um den humanisierten Wert einer Bereichsabfrage zu drucken, müssen Sie ihn zunächst von einer Zeitreihe auf einen Instantvektor mit einem Reduce-Ausdruck reduzieren. Anschließend können Sie das Ergebnis des Reduce-Ausdrucks drucken, indem Sie stattdessen dessen Ref-ID verwenden. Wenn der Reduce-Ausdruck beispielsweise den Durchschnitt von A verwendet und die Referenz-ID B hat, würden Sie schreiben:

{{ humanize (index $values "B").Value }}

Drucken Sie den Wert einer Abfrage als Prozentsatz

Um den Wert einer Sofortabfrage als Prozentsatz zu drucken, verwenden Sie die humanizePercentage Funktion:

{{ humanizePercentage (index $values "A").Value }}

Diese Funktion erwartet, dass der Wert eine Dezimalzahl zwischen 0 und 1 ist. Wenn der Wert stattdessen eine Dezimalzahl zwischen 0 und 100 ist, können Sie ihn entweder in Ihrer Abfrage oder mithilfe eines mathematischen Ausdrucks durch 100 teilen. Wenn es sich bei der Abfrage um eine Bereichsabfrage handelt, müssen Sie sie zunächst mit einem Reduce-Ausdruck von einer Zeitreihe auf einen Instantvektor reduzieren.

Legen Sie anhand des Werts einer Abfrage einen Schweregrad fest

Verwenden Sie eine if-Anweisung und die Vergleichsfunktion „Größer als“, um anhand des Werts einer Abfrage einen Schweregrad festzulegen. Achten Sie darauf, Dezimalzahlen (80.0,, usw.) zu verwenden 50.00.0, wenn Sie Vergleiche durchführen, $values da Text/Vorlage keinen Typenzwang unterstützt. Eine Liste aller unterstützten Vergleichsfunktionen finden Sie hier.

{{ if (gt $values.A.Value 80.0) -}}
high
{{ else if (gt $values.A.Value 50.0) -}}
medium
{{ else -}}
low
{{- end }}

Drucken Sie alle Etiketten aus einem klassischen Zustand

Sie können diese Option nicht verwenden$labels, um Etiketten aus der Abfrage zu drucken, wenn Sie klassische Bedingungen verwenden, und müssen $values stattdessen verwenden. Der Grund dafür ist, dass bei klassischen Bedingungen diese Bezeichnungen verworfen werden, um eindimensionales Verhalten zu erzwingen (maximal eine Warnung pro Warnungsregel). Wenn die klassischen Bedingungen diese Beschriftungen nicht verwerfen würden, würden Abfragen, die viele Zeitreihen zurückgaben, dazu führen, dass Warnungen ständig zwischen Auslösen und Auflösen hin und her schwanken, da sich die Beschriftungen bei jeder Auswertung der Warnungsregel ändern würden.

Stattdessen enthält die $values Variable die reduzierten Werte aller Zeitreihen für alle ausgelösten Bedingungen. Wenn Sie beispielsweise eine Warnungsregel mit einer Abfrage A haben, die zwei Zeitreihen zurückgibt, und einer klassischen Bedingung B mit zwei Bedingungen, dann $values würde sie B0B1, B2 und enthaltenB3. Wenn die klassische Bedingung B nur eine Bedingung hätte, $values würde sie nur B0 UND enthaltenB1.

Verwenden Sie die folgende Vorlage, um alle Beschriftungen aller Brennzeitreihen zu drucken (achten Sie darauf, den regulären Ausdruck durch die Ref-ID der klassischen Bedingung zu ersetzenB, falls diese anders ist):

{{ range $k, $v := $values -}}
{{ if (match "B[0-9]+" $k) -}}
{{ $k }}: {{ $v.Labels }}{{ end }}
{{ end }}

Zum Beispiel würde eine klassische Bedingung für zwei Zeitreihen, die eine einzige Bedingung überschreiten, ausgegeben:

B0: instance=server1
B1: instance=server2

Wenn die klassische Bedingung zwei oder mehr Bedingungen hat und eine Zeitreihe mehrere Bedingungen gleichzeitig überschreitet, werden ihre Bezeichnungen für jede Bedingung, die überschritten wird, dupliziert:

B0: instance=server1
B1: instance=server2
B2: instance=server1
B3: instance=server2

Wenn Sie eindeutige Beschriftungen drucken müssen, sollten Sie in Betracht ziehen, Ihre Warnungsregeln stattdessen von eindimensional auf mehrdimensional zu ändern. Sie können dies tun, indem Sie Ihre klassische Bedingung durch Reduce-Ausdrücke und mathematische Ausdrücke ersetzen.

Druckt alle Werte aus einer klassischen Bedingung

Um alle Werte einer klassischen Bedingung zu drucken, nehmen Sie das vorherige Beispiel und $v.Labels ersetzen Sie es durch$v.Value:

{{ range $k, $v := $values -}}
{{ if (match "B[0-9]+" $k) -}}
{{ $k }}: {{ $v.Value }}{{ end }}
{{ end }}

Eine klassische Bedingung für zwei Zeitreihen, die eine einzige Bedingung überschreiten, würde beispielsweise Folgendes ausgeben:

B0: 81.2345
B1: 84.5678

Wenn die klassische Bedingung zwei oder mehr Bedingungen hat und eine Zeitreihe mehrere Bedingungen gleichzeitig überschreitet, enthält $values sie die Werte aller Bedingungen:

B0: 81.2345
B1: 92.3456
B2: 84.5678
B3: 95.6789

Variablen

Die folgenden Variablen stehen Ihnen bei der Erstellung von Vorlagen für Beschriftungen und Anmerkungen zur Verfügung:

Die labels-Variable

Die $labels Variable enthält alle Labels aus der Abfrage. Angenommen, Sie haben eine Abfrage, die die CPU-Auslastung für alle Ihre Server zurückgibt, und Sie haben eine Warnungsregel, die ausgelöst wird, wenn einer Ihrer Server in den letzten 5 Minuten die CPU-Auslastung von 80% überschritten hat. Sie möchten der Warnung eine Zusammenfassung hinzufügen, die Ihnen mitteilt, auf welchem Server eine hohe CPU-Auslastung herrscht. Mit der $labels Variablen können Sie eine Vorlage schreiben, die einen für Menschen lesbaren Satz druckt, z. B.:

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes

Anmerkung

Wenn Sie eine klassische Bedingung verwenden, enthält $labels sie keine Labels aus der Abfrage. Bei klassischen Bedingungen werden diese Bezeichnungen verworfen, um eindimensionales Verhalten zu erzwingen (höchstens eine Warnung pro Warnungsregel). Wenn Sie Beschriftungen aus der Abfrage in Ihrer Vorlage verwenden möchten, folgen Sie dem vorherigen Beispiel Alle Beschriftungen aus einer klassischen Bedingung drucken.

Die Wertvariable

Die $value Variable ist eine Zeichenfolge, die die Bezeichnungen und Werte aller Sofortabfragen, Schwellenwerte, Reduktionsausdrücke und mathematische Ausdrücke sowie klassische Bedingungen in der Warnungsregel enthält. Sie enthält nicht die Ergebnisse von Bereichsabfragen, da diese zwischen 10 und 10.000 Zeilen oder Metriken zurückgeben können. Wenn dies der Fall wäre, könnte eine einzelne Warnung bei besonders großen Abfragen 10 MB Speicher beanspruchen, und Grafana würde sehr schnell der Speicher ausgehen.

Um die $value Variable in der Zusammenfassung auszudrucken, würden Sie etwa Folgendes schreiben:

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ $value }}

Und es würde ungefähr so aussehen:

CPU usage for instance1 has exceeded 80% for the last 5 minutes: [ var='A' labels={instance=instance1} value=81.234 ]

var='A'Bezieht sich hier auf die Sofortabfrage mit der Referenz-ID A, labels={instance=instance1} bezieht sich auf die Labels und value=81.234 bezieht sich auf die durchschnittliche CPU-Auslastung in den letzten 5 Minuten.

Wenn Sie nur einen Teil der Zeichenfolge statt der vollständigen Zeichenfolge drucken möchten, verwenden Sie die $values Variable. Sie enthält dieselben Informationen wie$value, aber in einer strukturierten Tabelle, und ist viel einfacher zu verwenden, als einen regulären Ausdruck zu schreiben, der nur dem gewünschten Text entspricht.

Die Wertevariable

Die $values Variable ist eine Tabelle, die die Bezeichnungen und Fließkommawerte aller Sofortabfragen und Ausdrücke enthält, die nach ihren Ref-IDs indexiert sind.

Um den Wert der Sofortabfrage mit der Ref-ID A zu drucken:

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "A" }}

Bei einer Warnung mit den Beschriftungen instance=server1 und einer Sofortabfrage mit dem Wert würde dies 81.2345 beispielsweise Folgendes ausgeben:

CPU usage for instance1 has exceeded 80% for the last 5 minutes: 81.2345

Wenn es sich bei der Abfrage in Ref ID A um eine Bereichsabfrage und nicht um eine Sofortabfrage handelt, fügen Sie einen Reduce-Ausdruck mit Ref ID B hinzu und ersetzen Sie ihn durch (index $values "A")(index $values "B"):

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "B" }}

Funktionen

Bei der Erstellung von Vorlagen für Beschriftungen und Anmerkungen stehen Ihnen die folgenden Funktionen zur Verfügung:

Argumente

Die args Funktion übersetzt eine Liste von Objekten in eine Map mit den Schlüsseln arg0, arg1 usw. Dies soll die Übergabe mehrerer Argumente an Vorlagen ermöglichen.

{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}

1 2

Externe URL

Die externalURL Funktion gibt die externe URL des Grafana-Servers zurück.

{{ externalURL }}

https://example.com/grafana

GraphLink

Die graphLink Funktion gibt den Pfad zur grafischen Ansicht Erkunden Sie in Grafana-Version 10 für den angegebenen Ausdruck und die angegebene Datenquelle zurück.

{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}

/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]

humanisieren

Die humanize Funktion humanisiert Dezimalzahlen.

{{ humanize 1000.0 }}

1k

humanisieren (1024)

Das humanize1024 funktioniert ähnlich wie, verwendet humanize aber 1024 statt 1000 als Basis.

{{ humanize1024 1024.0 }}

1ki

HumanizeDuration

Die humanizeDuration Funktion humanisiert eine Dauer in Sekunden.

{{ humanizeDuration 60.0 }}

1m 0s

Prozentsatz humanisieren

Die humanizePercentage Funktion humanisiert einen Verhältniswert zu einem Prozentsatz.

{{ humanizePercentage 0.2 }}

20%

HumanizeTimestamp

Die humanizeTimestamp Funktion humanisiert einen Unix-Zeitstempel.

{{ humanizeTimestamp 1577836800.0 }}

2020-01-01 00:00:00 +0000 UTC

Spiel

Die match Funktion gleicht den Text mit einem regulären Ausdrucksmuster ab.

{{ match "a.*" "abc" }}

true

Pfad/Präfix

Die pathPrefix Funktion gibt den Pfad des Grafana-Servers zurück.

{{ pathPrefix }}

/grafana

TableLink

Die tableLink Funktion gibt den Pfad zur Tabellenansicht Erkunden Sie in Grafana-Version 10 für den angegebenen Ausdruck und die angegebene Datenquelle zurück.

{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}

/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]

Titel

Die title Funktion schreibt das erste Zeichen jedes Worts groß.

{{ title "hello, world!" }}

Hello, World!

toLower

Die toLower Funktion gibt den gesamten Text in Kleinbuchstaben zurück.

{{ toLower "Hello, world!" }}

hello, world!

toUpper

Die toUpper Funktion gibt den gesamten Text in Großbuchstaben zurück.

{{ toUpper "Hello, world!" }}

HELLO, WORLD!

reReplaceAll

Die reReplaceAll Funktion ersetzt Text, der dem regulären Ausdruck entspricht.

{{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}

example.com:8080