Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Modelli di etichette e annotazioni
****
**Questo argomento della documentazione è progettato per le aree di lavoro Grafana che supportano la versione 12.x di Grafana.**
Per le aree di lavoro Grafana che supportano la versione 10.x di Grafana, vedere. [Funzionamento nella versione 10 di Grafana](using-grafana-v10.md)
Per le aree di lavoro Grafana che supportano la versione 9.x di Grafana, vedere. [Funzionamento in Grafana versione 9](using-grafana-v9.md)
Per le aree di lavoro Grafana che supportano la versione 8.x di Grafana, vedere. [Funzionamento in Grafana versione 8](using-grafana-v8.md)
È 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. [text/template](https://pkg.go.dev/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 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, text/template consulta la [text/template](https://pkg.go.dev/text/template)documentazione.
**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 usage``instance=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](#v12-alerting-overview-labels-templating-the-labels-variable).
**Stampa tutte le etichette, una per riga**
Per stampare tutte le etichette, una per riga, usa a per `range` iterare su ogni key/value coppia 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 usage``instance=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](#v12-alerting-overview-labels-templating-the-labels-variable).
**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'etichetta`instance=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](#v12-alerting-overview-labels-templating-the-labels-variable).
**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, è necessario innanzitutto 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``0.0`, ecc.) quando esegui confronti con `$values` poiché non text/template supporta la coercizione dei tipi. [Puoi trovare un elenco di tutte le funzioni di confronto supportate qui.](https://pkg.go.dev/text/template#hdr-Functions)
```
{{ 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 `B0``B1`, `B2` e`B3`. Se la condizione classica B avesse una sola condizione, `$values` conterrebbe solo `B0` e`B1`.
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
```
## Variabili
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 valore`81.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 12 di Grafana](v12-explore.md) 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**
`humanize1024`Funziona 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 12 di Grafana](v12-explore.md) 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!
```
**re ReplaceAll**
La `reReplaceAll` funzione sostituisce il testo corrispondente all'espressione regolare.
```
{{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}
```
```
example.com:8080
```