Usando a linguagem de modelagem de Go

Este tópico de documentação foi desenvolvido para espaços de trabalho do Grafana que oferecem suporte ao Grafana versão 9.x.

Para espaços de trabalho do Grafana que suportam a versão 10.x do Grafana, consulte. Trabalhando na versão 10 do Grafana

Para espaços de trabalho do Grafana que suportam a versão 8.x do Grafana, consulte. Trabalhando na versão 8 da Grafana

Você escreve modelos de notificação na linguagem de modelagem do Go, texto/modelo.

Esta seção fornece uma visão geral da linguagem de modelagem e dos modelos de escrita do Go em texto/modelo.

Ponto

Em texto/modelo, há um cursor especial chamado ponto e é escrito como. . Você pode pensar nesse cursor como uma variável cujo valor muda dependendo de onde ele é usado no modelo. Por exemplo, no início de um modelo de notificação, . refere-se ao ExtendedData objeto, que contém vários camposAlerts, incluindo StatusGroupLabels,CommonLabels,, CommonAnnotations ExternalURL e. No entanto, ponto pode se referir a outra coisa quando usado em uma lista range acima de uma lista, quando usado dentro de uma with ou ao escrever modelos de recursos para serem usados em outros modelos. Você pode ver exemplos disso emCrie modelos de notificação, e todos os dados e funções noReferência do modelo.

Tags de abertura e fechamento

Em texto/modelo, os modelos começam com {{ e terminam com, }} independentemente de o modelo imprimir uma variável ou executar estruturas de controle, como instruções if. Isso é diferente de outras linguagens de modelagem, como Jinja, em que a impressão de uma variável usa e. {{ }} e as estruturas de controle usam e. {% %}

Print (Imprimir)

Para imprimir o valor de algo, use {{ }} e. Você pode imprimir o valor do ponto, um campo do ponto, o resultado de uma função e o valor de uma variável. Por exemplo, para imprimir o Alerts campo ao qual o ponto se refere, ExtendedData você escreveria o seguinte:

{{ .Alerts }}

Repita os alertas

Para imprimir apenas as etiquetas de cada alerta, em vez de todas as informações sobre o alerta, você pode usar a range para iterar os alertas emExtendedData:

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

Dentro do intervalo, o ponto não se refere mais aExtendedData, mas a umAlert. Você pode usar {{ .Labels }} para imprimir as etiquetas de cada alerta. Isso funciona porque {{ range .Alerts }} altera o ponto para se referir ao alerta atual na lista de alertas. Quando o intervalo termina, o ponto é redefinido para o valor que tinha antes do início do intervalo, que neste exemplo éExtendedData:

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

Repita sobre anotações e rótulos

Vamos escrever um modelo para imprimir as etiquetas de cada alerta no formatoThe name of the label is $name, and the value is $value, onde $name e $value conter o nome e o valor de cada etiqueta.

Como no exemplo anterior, use um intervalo para iterar sobre os alertas de .Alerts forma que o ponto se refira ao alerta atual na lista de alertas e, em seguida, use um segundo intervalo nos rótulos classificados para que o ponto seja atualizado uma segunda vez para se referir ao rótulo atual. Dentro do segundo intervalo, use .Name e .Value para imprimir o nome e o valor de cada etiqueta:

{{ 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 }}

Se as declarações

Você pode usar instruções if em modelos. Por exemplo, para imprimir There are no alerts se não houver alertas, .Alerts você escreveria o seguinte:

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

Com

With é semelhante às instruções if, porém, diferentemente das instruções if, with atualiza o ponto para se referir ao valor de with:

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

Variáveis

As variáveis no texto/modelo devem ser criadas dentro do modelo. Por exemplo, para criar uma variável chamada $variable com o valor atual de ponto, você escreveria o seguinte:

{{ $variable := . }}

Você pode usar $variable dentro de um intervalo ou with se referirá ao valor do ponto no momento em que a variável foi definida, não ao valor atual do ponto.

Por exemplo, você não pode escrever um modelo que use {{ .Labels }} no segundo intervalo porque aqui o ponto se refere ao rótulo atual, não ao alerta atual:

{{ 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 }}

Você pode corrigir isso definindo uma variável chamada $alert no primeiro intervalo e antes do segundo intervalo:

{{ 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 }}

Intervalo com índice

Você pode obter o índice de cada alerta dentro de um intervalo definindo variáveis de índice e valor no início do intervalo:

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

Definir modelos

Você pode definir modelos que podem ser usados em outros modelos, usando define e o nome do modelo entre aspas duplas. Você não deve definir modelos com o mesmo nome de outros modelos, incluindo modelos padrão__subject, como __text_values_list__text_alert_list,, default.title default.message e. Quando um modelo foi criado com o mesmo nome de um modelo padrão ou um modelo em outro modelo de notificação, o Grafana pode usar qualquer um dos modelos. Grafana não impede nem mostra uma mensagem de erro quando há dois ou mais modelos com o mesmo nome.

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

Incorporar modelos

Você pode incorporar um modelo definido em seu modelo usando template o nome do modelo entre aspas duplas e o cursor que deve ser passado para o modelo:

{{ template "print_labels" . }}

Transmita dados para modelos

Dentro de um modelo, o ponto se refere ao valor que é passado para o modelo.

Por exemplo, se um modelo receber uma lista de alertas de disparo, ponto se referirá a essa lista de alertas de disparo:

{{ template "print_alerts" .Alerts }}

Se o modelo receber os rótulos classificados para um alerta, o ponto se referirá à lista de rótulos classificados:

{{ template "print_labels" .SortedLabels }}

Isso é útil ao escrever modelos reutilizáveis. Por exemplo, para imprimir todos os alertas, você pode escrever o seguinte:

{{ template "print_alerts" .Alerts }}

Então, para imprimir apenas os alertas de disparo, você pode escrever o seguinte:

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

Isso funciona porque ambos .Alerts .Alerts.Firing são listas de alertas.

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

Comentários

Você pode adicionar comentários com {{/* e*/}}:

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

Para evitar que comentários adicionem quebras de linha, use:

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

Indentação

Você pode usar recuo, tanto tabulações quanto espaços, e quebras de linha, para tornar os modelos mais legíveis:

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

No entanto, o recuo no modelo também estará presente no texto. A seguir, veremos como removê-lo.

Remova espaços e quebras de linha

Em texto/modelo, use {{- e -}} para remover espaços à esquerda e à direita e quebras de linha.

Por exemplo, ao usar recuo e quebras de linha para tornar um modelo mais legível:

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

O recuo e as quebras de linha também estarão presentes no texto:

    alertname = "Test"

    grafana_folder = "Test alerts"

Você pode remover o recuo e as quebras de linha do texto, alterando }} para -}} no início de cada intervalo:

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

O recuo e as quebras de linha no modelo agora estão ausentes do texto:

alertname = "Test"
grafana_folder = "Test alerts"