Modelli di etichette e annotazioni

Questo argomento della documentazione è progettato per le aree di lavoro Grafana che supportano la versione 10.x di Grafana.

Per le aree di lavoro Grafana che supportano la versione 9.x di Grafana, vedere. Lavorare nella versione 9 di Grafana

Per le aree di lavoro Grafana che supportano la versione 8.x di Grafana, vedere. Funzionamento in Grafana versione 8

È possibile utilizzare modelli per includere dati provenienti da interrogazioni ed espressioni in etichette e annotazioni. Ad esempio, potresti voler impostare l'etichetta di gravità per un avviso in base al valore della query o utilizzare l'etichetta dell'istanza della query in un'annotazione di riepilogo in modo da sapere quale server sta riscontrando un utilizzo elevato della CPU.

Tutti i modelli devono essere scritti in text/template. Indipendentemente dal fatto che stiate creando un modello di etichetta o di un'annotazione, dovreste scrivere ogni modello in linea all'interno dell'etichetta o dell'annotazione che state modellando. Ciò significa che non è possibile condividere modelli tra etichette e annotazioni e sarà invece necessario copiare i modelli ovunque si desideri utilizzarli.

Ogni modello viene valutato ogni volta che viene valutata la regola di avviso e viene valutato separatamente per ogni avviso. Ad esempio, se la regola di avviso ha un'annotazione di riepilogo basata su un modello e la regola di avviso ha 10 avvisi di attivazione, il modello verrà eseguito 10 volte, una volta per ogni avviso. Dovresti cercare di evitare il più possibile di eseguire calcoli costosi nei tuoi modelli.

Esempi

Piuttosto che scrivere un tutorial completo su text/template, i seguenti esempi cercano di mostrare i casi d'uso più comuni che abbiamo visto per i modelli. Puoi usare questi esempi alla lettera o adattarli secondo necessità al tuo caso d'uso. Per ulteriori informazioni su come scrivere testo/modello, consulta la documentazione di text/template.

Stampa tutte le etichette, separate da virgole

Per stampare tutte le etichette, separate da virgole, stampa la $labels variabile:

{{ $labels }}

Ad esempio, se viene fornito un avviso con le etichette alertname=High CPU usageinstance=server1, grafana_folder=CPU alerts verrà stampato:

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

Nota

Se si utilizzano condizioni classiche, $labels non conterrà alcuna etichetta della query. Per ulteriori informazioni, fare riferimento alla variabile $labels.

Stampa tutte le etichette, una per riga

Per stampare tutte le etichette, una per riga, usa a per range iterare su ogni coppia chiave/valore e stamparle singolarmente. Qui $k si riferisce al nome e $v al valore dell'etichetta corrente:

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

Ad esempio, se viene fornito un avviso con le etichette alertname=High CPU usageinstance=server1, grafana_folder=CPU alerts verrà stampato:

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

Nota

Se si utilizzano condizioni classiche, $labels non conterrà alcuna etichetta della query. Per ulteriori informazioni, fare riferimento alla variabile $labels.

Stampa una singola etichetta

Per stampare una singola etichetta usa la index funzione con la $labels variabile:

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

Ad esempio, dato un avviso con l'etichettainstance=server1, questo stamperebbe:

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

Nota

Se si utilizzano condizioni classiche, $labels non conterrà alcuna etichetta della query. Per ulteriori informazioni, fare riferimento alla variabile $labels.

Stampa il valore di una query

Per stampare il valore di una query istantanea è possibile stampare il relativo Ref ID utilizzando la index funzione e la $values variabile:

{{ index $values "A" }}

Ad esempio, data una query istantanea che restituisce il valore 81.2345, verrà stampato:

81.2345

Per stampare il valore di una query con intervallo, è necessario innanzitutto ridurlo da una serie temporale a un vettore istantaneo con un'espressione di riduzione. È quindi possibile stampare il risultato dell'espressione reduce utilizzando invece il relativo ID Ref. Ad esempio, se l'espressione reduce prende la media di A e ha l'ID Ref B, dovresti scrivere:

{{ index $values "B" }}

Stampa il valore umanizzato di una query

Per stampare il valore umanizzato di una query istantanea usa la humanize funzione:

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

Ad esempio, data una query istantanea che restituisce il valore 81.2345, verrà stampato:

81.234

Per stampare il valore umanizzato di una query con intervallo, è necessario innanzitutto ridurlo da una serie temporale a un vettore istantaneo con un'espressione di riduzione. È quindi possibile stampare il risultato dell'espressione reduce utilizzando invece il relativo ID Ref. Ad esempio, se l'espressione reduce prende la media di A e ha l'ID Ref B, dovresti scrivere:

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

Stampa il valore di una query in percentuale

Per stampare il valore di una query istantanea in percentuale, usa la humanizePercentage funzione:

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

Questa funzione prevede che il valore sia un numero decimale compreso tra 0 e 1. Se il valore è invece un numero decimale compreso tra 0 e 100, è possibile dividerlo per 100 nella query o utilizzando un'espressione matematica. Se la query è una query a intervallo, devi prima ridurla da una serie temporale a un vettore istantaneo con un'espressione di riduzione.

Imposta una severità in base al valore di una query

Per impostare un'etichetta di gravità in base al valore di una query, utilizzate l'istruzione if e la funzione greater than comparison. Assicurati di utilizzare i decimali (80.0,,50.0, ecc.) quando esegui i confronti0.0, $values poiché il testo/modello non supporta la coercizione dei tipi. Puoi trovare un elenco di tutte le funzioni di confronto supportate qui.

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

Stampa tutte le etichette partendo da una condizione classica

Non è possibile $labels stampare etichette dalla query se si utilizzano condizioni classiche, ma è necessario utilizzare $values al suo posto. Il motivo è che le condizioni classiche scartano queste etichette per imporre un comportamento unidimensionale (al massimo un avviso per regola di avviso). Se le condizioni classiche non eliminassero queste etichette, le interrogazioni che restituivano numerose serie temporali farebbero sì che gli avvisi si alternassero tra l'attivazione e la risoluzione costante, poiché le etichette cambierebbero ogni volta che veniva valutata la regola di avviso.

La $values variabile contiene invece i valori ridotti di tutte le serie temporali per tutte le condizioni che si verificano. Ad esempio, se hai una regola di avviso con una query A che restituisce due serie temporali e una condizione classica B con due condizioni, allora $values conterrebbe B0B1, B2 eB3. Se la condizione classica B avesse una sola condizione, $values conterrebbe solo B0 eB1.

Per stampare tutte le etichette di tutte le serie storiche di cottura, usa il seguente modello (assicurati di sostituirlo B nell'espressione regolare con l'ID Ref della condizione classica se è diversa):

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

Ad esempio, una condizione classica per due serie temporali che superano una singola condizione stamperebbe:

B0: instance=server1
B1: instance=server2

Se la condizione classica presenta due o più condizioni e una serie temporale supera più condizioni contemporaneamente, le relative etichette verranno duplicate per ogni condizione superata:

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

Se devi stampare etichette uniche, dovresti invece prendere in considerazione la possibilità di modificare le regole di avviso da unidimensionali a multidimensionali. Puoi farlo sostituendo la tua condizione classica con espressioni di riduzione e matematiche.

Stampa tutti i valori da una condizione classica

Per stampare tutti i valori di una condizione classica, prendi l'esempio precedente e sostituiscilo $v.Labels con$v.Value:

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

Ad esempio, una condizione classica per due serie temporali che superano una singola condizione stamperebbe:

B0: 81.2345
B1: 84.5678

Se la condizione classica ha due o più condizioni e una serie temporale supera più condizioni contemporaneamente, $values conterrà i valori di tutte le condizioni:

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

Variables

Le seguenti variabili sono disponibili per la creazione di modelli di etichette e annotazioni:

La variabile labels

La $labels variabile contiene tutte le etichette della query. Ad esempio, supponiamo di avere una query che restituisce l'utilizzo della CPU per tutti i server e di avere una regola di avviso che si attiva quando uno dei server ha superato l'80% di utilizzo della CPU negli ultimi 5 minuti. Desideri aggiungere un'annotazione di riepilogo all'avviso che indichi quale server sta riscontrando un utilizzo elevato della CPU. Con la $labels variabile puoi scrivere un modello che stampa una frase leggibile dall'uomo come:

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

Nota

Se si utilizza una condizione classica, $labels non conterrà alcuna etichetta della query. Le condizioni classiche eliminano queste etichette per imporre un comportamento unidimensionale (al massimo un avviso per regola di avviso). Se desideri utilizzare le etichette della query nel tuo modello, segui il precedente esempio Stampa tutte le etichette da una condizione classica.

La variabile value

La $value variabile è una stringa contenente le etichette e i valori di tutte le query istantanee, le espressioni threshold, reduce e matematiche e le condizioni classiche nella regola di avviso. Non contiene i risultati delle interrogazioni con intervalli, in quanto possono restituire da 10 a 10.000 righe o metriche. In tal caso, per query particolarmente grandi un singolo avviso potrebbe utilizzare decine di MB di memoria e Grafana esaurirebbe la memoria molto rapidamente.

Per stampare la $value variabile nel riepilogo dovresti scrivere qualcosa del genere:

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

E sarebbe simile a questo:

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

Qui var='A' si riferisce alla query istantanea con Ref ID A, labels={instance=instance1} si riferisce alle etichette e value=81.234 si riferisce all'utilizzo medio della CPU negli ultimi 5 minuti.

Se vuoi stampare solo una parte della stringa invece della stringa completa, usa la $values variabile. Contiene le stesse informazioni$value, ma in una tabella strutturata, ed è molto più facile da usare rispetto alla scrittura di un'espressione regolare che corrisponda solo al testo desiderato.

La variabile values

La $values variabile è una tabella contenente le etichette e i valori in virgola mobile di tutte le query e le espressioni istantanee, indicizzate in base ai relativi ID Ref.

Per stampare il valore della query istantanea con Ref ID A:

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

Ad esempio, dato un avviso con le etichette instance=server1 e una query istantanea con il valore81.2345, questo stamperebbe:

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

Se la query in Ref ID A è una query di intervallo anziché una query istantanea, aggiungi un'espressione di riduzione con Ref ID B e sostituiscila (index $values "A") con(index $values "B"):

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

Funzioni

Le seguenti funzioni sono disponibili per la creazione di modelli di etichette e annotazioni:

args

La args funzione traduce un elenco di oggetti in una mappa con le chiavi arg0, arg1 ecc. Questo ha lo scopo di consentire il passaggio di più argomenti ai modelli.

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

1 2

URL esterno

La externalURL funzione restituisce l'URL esterno del server Grafana.

{{ externalURL }}

https://example.com/grafana

GraphLink

La graphLink funzione restituisce il percorso della visualizzazione grafica Esplora nella versione 10 di Grafana per l'espressione e l'origine dati specificate.

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

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

umanizzare

La humanize funzione umanizza i numeri decimali.

{{ humanize 1000.0 }}

1k

umanizza 1024

humanize1024Funziona in modo simile humanize ma utilizza 1024 come base anziché 1000.

{{ humanize1024 1024.0 }}

1ki

Durata umanizzata

La humanizeDuration funzione umanizza una durata in secondi.

{{ humanizeDuration 60.0 }}

1m 0s

Umanizza la percentuale

La humanizePercentage funzione umanizza un valore di rapporto rispetto a una percentuale.

{{ humanizePercentage 0.2 }}

20%

Umanizza il timestamp

La humanizeTimestamp funzione umanizza un timestamp Unix.

{{ humanizeTimestamp 1577836800.0 }}

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

partita

La match funzione abbina il testo a un modello di espressione regolare.

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

true

PathPrefix

La pathPrefix funzione restituisce il percorso del server Grafana.

{{ pathPrefix }}

/grafana

TableLink

La tableLink funzione restituisce il percorso della vista tabulare Esplora nella versione 10 di Grafana per l'espressione e l'origine dati specificate.

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

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

titolo

La title funzione rende maiuscolo il primo carattere di ogni parola.

{{ title "hello, world!" }}

Hello, World!

a Lower

La toLower funzione restituisce tutto il testo in lettere minuscole.

{{ toLower "Hello, world!" }}

hello, world!

a TOUPPER

La toUpper funzione restituisce tutto il testo in maiuscolo.

{{ toUpper "Hello, world!" }}

HELLO, WORLD!

reReplaceAll

La reReplaceAll funzione sostituisce il testo corrispondente all'espressione regolare.

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

example.com:8080