Usare il linguaggio di template di Go

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

Scrivi modelli di notifica nel linguaggio di template di Go, text/template.

Questa sezione fornisce una panoramica del linguaggio di template di Go e dei modelli di scrittura in text/template.

Dot

Nel testo/modello c'è un cursore speciale chiamato punto, ed è scritto come. . Puoi pensare a questo cursore come a una variabile il cui valore cambia a seconda del punto del modello in cui viene utilizzato. Ad esempio, all'inizio di un modello di notifica . si fa riferimento all'ExtendedDataoggetto, che contiene una serie di campi tra cui AlertsStatus, GroupLabelsCommonLabels, CommonAnnotations eExternalURL. Tuttavia, dot potrebbe fare riferimento a qualcos'altro quando viene utilizzato in un elenco range superiore a un elenco, quando viene utilizzato all'interno di un with o quando si scrivono modelli di funzionalità da utilizzare in altri modelli. Puoi vederne alcuni esempi inCrea modelli di notifica, e tutti i dati e le funzioni inRiferimento modello.

Tag di apertura e chiusura

In text/template, i modelli iniziano {{ e finiscono con }} indipendentemente dal fatto che il modello stampi una variabile o esegua strutture di controllo come le istruzioni if. Questo è diverso da altri linguaggi di template come Jinja, dove la stampa di una variabile utilizza {{ e e le strutture di controllo utilizzano e}}. {% %}

Print (Stampa)

Per stampare il valore di qualcosa usa e. {{ }} È possibile stampare il valore di un punto, un campo di punti, il risultato di una funzione e il valore di una variabile. Ad esempio, per stampare il Alerts campo a cui si riferisce il punto ExtendedData devi scrivere quanto segue:

{{ .Alerts }}

Esegui iterazioni sugli avvisi

Per stampare solo le etichette di ogni avviso, anziché tutte le informazioni sull'avviso, puoi utilizzare range a per ripetere gli avvisi in: ExtendedData

{{ range .Alerts }}
{{ .Labels }}
{{ end }}

All'interno dell'intervallo il punto non si riferisce più aExtendedData, ma a un. Alert È possibile utilizzare {{ .Labels }} per stampare le etichette di ogni avviso. Funziona perché {{ range .Alerts }} cambia il punto per fare riferimento all'avviso corrente nell'elenco degli avvisi. Quando l'intervallo è terminato, il punto viene ripristinato al valore che aveva prima dell'inizio dell'intervallo, che in questo esempio èExtendedData:

{{ range .Alerts }}
{{ .Labels }}
{{ end }}
{{/* does not work, .Labels does not exist here */}}
{{ .Labels }}
{{/* works, cursor was reset */}}
{{ .Status }}

Esegui iterazioni su annotazioni ed etichette

Scriviamo un modello per stampare le etichette di ogni avviso nel formatoThe name of the label is $name, and the value is $value, dove $name e $value contiene il nome e il valore di ogni etichetta.

Come nell'esempio precedente, utilizzate un intervallo per scorrere gli avvisi in .Alerts modo che il punto si riferisca all'avviso corrente nell'elenco degli avvisi, quindi utilizzate un secondo intervallo sulle etichette ordinate in modo che dot venga aggiornato una seconda volta per fare riferimento all'etichetta corrente. All'interno del secondo intervallo usa .Name e stampa .Value il nome e il valore di ogni etichetta:

{{ range .Alerts }}
{{ range .Labels.SortedPairs }}
The name of the label is {{ .Name }}, and the value is {{ .Value }}
{{ end }}
{{ range .Annotations.SortedPairs }}
The name of the annotation is {{ .Name }}, and the value is {{ .Value }}
{{ end }}
{{ end }}

Le funzioni dell'indice

Per stampare un'annotazione o un'etichetta specifica, usa la index funzione.

{{ range .Alerts }}
The name of the alert is {{ index .Labels "alertname" }}
{{ end }}

Dichiarazioni If

È possibile utilizzare le istruzioni if nei modelli. Ad esempio, per stampare There are no alerts se non sono presenti avvisi, .Alerts è necessario scrivere quanto segue:

{{ if .Alerts }}
There are alerts
{{ else }}
There are no alerts
{{ end }}

Con

With è simile alle istruzioni if, tuttavia a differenza delle istruzioni if, with aggiorna dot per fare riferimento al valore di with:

{{ with .Alerts }}
There are {{ len . }} alert(s)
{{ else }}
There are no alerts
{{ end }}

Variables

Le variabili in text/template devono essere create all'interno del modello. Ad esempio, per creare una variabile chiamata $variable con il valore corrente di dot devi scrivere quanto segue:

{{ $variable := . }}

Puoi usare $variable all'interno di un intervallo o with e farà riferimento al valore di dot nel momento in cui la variabile è stata definita, non al valore corrente di dot.

Ad esempio, non puoi scrivere un modello da utilizzare {{ .Labels }} nel secondo intervallo perché qui il punto si riferisce all'etichetta corrente, non all'avviso corrente:

{{ range .Alerts }}
{{ range .Labels.SortedPairs }}
{{ .Name }} = {{ .Value }}
{{/* does not work because in the second range . is a label not an alert */}}
There are {{ len .Labels }}
{{ end }}
{{ end }}

Puoi risolvere questo problema definendo una variabile chiamata $alert nel primo intervallo e prima del secondo intervallo:

{{ range .Alerts }}
{{ $alert := . }}
{{ range .Labels.SortedPairs }}
{{ .Name }} = {{ .Value }}
{{/* works because $alert refers to the value of dot inside the first range */}}
There are {{ len $alert.Labels }}
{{ end }}
{{ end }}

Intervallo con indice

È possibile ottenere l'indice di ogni avviso all'interno di un intervallo definendo le variabili di indice e valore all'inizio dell'intervallo:

{{ $num_alerts := len .Alerts }}
{{ range $index, $alert := .Alerts }}
This is alert {{ $index }} out of {{ $num_alerts }}
{{ end }}

Definire i modelli

È possibile definire modelli che possono essere utilizzati all'interno di altri modelli, utilizzando define e il nome del modello tra virgolette doppie. Non è necessario definire modelli con lo stesso nome di altri modelli, inclusi modelli predefiniti come __subject__text_values_list,__text_alert_list, default.title edefault.message. Se è stato creato un modello con lo stesso nome di un modello predefinito o un modello in un altro modello di notifica, Grafana potrebbe utilizzare entrambi i modelli. Grafana non impedisce o mostra un messaggio di errore quando ci sono due o più modelli con lo stesso nome.

{{ define "print_labels" }}
{{ end }}

Esegui modelli

È possibile eseguire un modello definito all'interno del modello utilizzando template il nome del modello tra virgolette doppie e il cursore da passare al modello:

{{ template "print_labels" . }}

Passa i dati ai modelli

All'interno di un modello, il punto si riferisce al valore passato al modello.

Ad esempio, se a un modello viene passato un elenco di avvisi di attivazione, dot si riferisce a quell'elenco di avvisi di attivazione:

{{ template "print_alerts" .Alerts }}

Se al modello vengono passate le etichette ordinate per un avviso, dot si riferisce all'elenco di etichette ordinate:

{{ template "print_labels" .SortedLabels }}

Questo è utile quando si scrivono modelli riutilizzabili. Ad esempio, per stampare tutti gli avvisi potresti scrivere quanto segue:

{{ template "print_alerts" .Alerts }}

Quindi, per stampare solo gli avvisi di attivazione, puoi scrivere questo:

{{ template "print_alerts" .Alerts.Firing }}

Funziona perché entrambi .Alerts .Alerts.Firing sono elenchi di avvisi.

{{ define "print_alerts" }}
{{ range . }}
{{ template "print_labels" .SortedLabels }}
{{ end }}
{{ end }}

Commenti

Puoi aggiungere commenti con {{/* e*/}}:

{{/* This is a comment */}}

Per evitare che i commenti aggiungano interruzioni di riga, usa:

{{- /* This is a comment with no leading or trailing line breaks */ -}}

Indentazione

Puoi usare l'indentazione, sia di tabulazioni che di spazi, e le interruzioni di riga, per rendere i modelli più leggibili:

{{ range .Alerts }}
  {{ range .Labels.SortedPairs }}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

Tuttavia, l'indentazione nel modello sarà presente anche nel testo. Successivamente vedremo come rimuoverlo.

Rimuovi spazi e interruzioni di riga

Nell'uso di testo/modello {{- e -}} per rimuovere gli spazi iniziali e finali e le interruzioni di riga.

Ad esempio, quando si utilizzano indentazioni e interruzioni di riga per rendere un modello più leggibile:

{{ range .Alerts }}
  {{ range .Labels.SortedPairs }}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

L'indentazione e le interruzioni di riga saranno presenti anche nel testo:

    alertname = "Test"

    grafana_folder = "Test alerts"

Puoi rimuovere i rientri e le interruzioni di riga dal testo cambiando la posizione }} -}} all'inizio di ogni intervallo:

{{ range .Alerts -}}
  {{ range .Labels.SortedPairs -}}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

I rientri e le interruzioni di riga nel modello sono ora assenti dal testo:

alertname = "Test"
grafana_folder = "Test alerts"