Usar a linguagem de modelos do Go

Este tópico de documentação foi desenvolvido para espaços de trabalho do Grafana compatíveis com o Grafana versão 9.x.

Para espaços de trabalho do Grafana compatíveis com o Grafana versão 10.x, consulte Trabalhar no Grafana versão 10.

Para espaços de trabalho do Grafana compatíveis com o Grafana versão 8.x, consulte Trabalhar no Grafana versão 8.

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

Esta seção fornece uma visão geral da linguagem de modelos 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 objeto ExtendedData, que contém vários campos, incluindo Alerts, Status, GroupLabels, CommonLabels, CommonAnnotations e ExternalURL. No entanto, ponto pode se referir a outra coisa quando usado em um range em uma lista, quando usado dentro de um with ou ao escrever modelos de recursos para serem usados em outros modelos. Você pode ver exemplos disso em Criar modelos de notificações, e todos os dados e funções na Referê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 modelos, 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 campo Alerts em que o ponto se refere a ExtendedData, você escreve o seguinte:

{{ .Alerts }}

Iterar em alertas

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

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

Dentro do intervalo, o ponto não mais se refere a ExtendedData, mas a um Alert. Você pode usar {{ .Labels }} para imprimir os rótulos 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 }}

Iterar em anotações e rótulos

Vamos escrever um modelo para imprimir os rótulos de cada alerta no formato The name of the label is $name, and the value is $value, em que $name e $value contêm o nome e o valor de cada rótulo.

Como no exemplo anterior, use um intervalo para iterar nos alertas em .Alerts de 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 rótulo:

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

Instruções If

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

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

With

With é semelhante às instruções if, porém, diferentemente das instruções if, o with atualiza o ponto para se referir ao valor do 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ê escreve o seguinte:

{{ $variable := . }}

Você pode usar $variable dentro de um intervalo ou with e vai 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 em 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, como __subject, __text_values_list, __text_alert_list, default.title e default.message. 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. O Grafana não impossibilita 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" . }}

Passar dados para modelos

Em um modelo, o ponto refere-se ao valor que é passado para o modelo.

Por exemplo, se um modelo receber uma lista de alertas disparados, o ponto então vai se referir a essa lista de alertas disparados:

{{ template "print_alerts" .Alerts }}

Se o modelo receber os rótulos classificados para um alerta, o ponto então vai 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 }}

Depois, para imprimir apenas os alertas disparados, você pode escrever o seguinte:

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

Isso funciona porque tanto .Alerts como .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 */ -}}

Recuo

Você pode usar recuo, tabs e 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.

Remover 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"