Uso del lenguaje de creación de plantillas de Go

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Las plantillas de notificaciones se escriben en el lenguaje de plantillas de Go, texto/plantilla.

En esta sección se proporciona información general sobre el lenguaje de creación de plantillas de Go y las plantillas de escritura en texto/plantilla.

Punto

En el texto/plantilla hay un cursor especial llamado punto que se escribe .. Puede pensar en este cursor como una variable cuyo valor cambia según el lugar de la plantilla en el que se utilice. Por ejemplo, al principio de una plantilla de notificación . hace referencia al objeto ExtendedData, que contiene varios campos, entre los que se incluyen Alerts, Status, GroupLabels, CommonLabels, CommonAnnotations y ExternalURL. Sin embargo, el punto puede hacer referencia a otra cosa cuando se usa en un range sobre una lista, cuando se usa dentro de with o cuando se escriben plantillas de características que se van a usar en otras plantillas. Puede ver ejemplos de esto en Creación de plantillas de notificaciones y todos los datos y funciones en la Referencia de la plantilla.

Etiquetas de apertura y cierre

En texto/plantilla, las plantillas comienzan por {{ y terminan en }}, independientemente de si la plantilla imprime una variable o ejecuta estructuras de control, como las instrucciones if. Se diferencia en esto de otros lenguajes de creación de plantillas, como Jinja, donde la impresión de una variable usa {{ y }}, y las estructuras de control usan {% y %}.

Print (Imprimir)

Para imprimir el valor de algo, use {{ y }}. Puede imprimir el valor de un punto, un campo de punto, el resultado de una función y el valor de una variable. Por ejemplo, para imprimir el campo Alerts donde el punto hace referencia a ExtendedData, escribiría lo siguiente:

{{ .Alerts }}

Iteración en alertas

Para imprimir solo las etiquetas de cada alerta, en lugar de toda la información sobre la alerta, puede usar range para iterar las alertas en ExtendedData:

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

Dentro del rango, el punto ya no hace referencia a ExtendedData, sino a una Alert. Puede utilizar {{ .Labels }} para imprimir las etiquetas de cada alerta. Esto funciona porque {{ range .Alerts }} cambia el punto para hacer referencia a la alerta actual de la lista de alertas. Cuando el rango finaliza, el punto se restablece al valor que tenía antes del inicio del rango, que en este ejemplo es ExtendedData:

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

Iteración en anotaciones y etiquetas

Vamos a escribir una plantilla para imprimir las etiquetas de cada alerta en el formato The name of the label is $name, and the value is $value, donde $name y $value contienen el nombre y el valor de cada etiqueta.

Como en el ejemplo anterior, utilice un rango para recorrer las alertas en iteración en .Alerts de forma que el punto haga referencia a la alerta actual de la lista de alertas y, a continuación, utilice un segundo rango en las etiquetas ordenadas para que el punto se actualice por segunda vez para hacer referencia a la etiqueta actual. Dentro del segundo rango, utilice .Name e .Value para imprimir el nombre y el 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 }}

Las funciones de índice

Para imprimir una anotación o etiqueta específica, utilice la función index.

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

Instrucciones if

Puede usar las instrucciones if en las plantillas. Por ejemplo, para imprimir There are no alerts si no hay alertas, en .Alerts escribiría lo siguiente:

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

With

With es similar a las instrucciones if, pero a diferencia de las instrucciones if, with actualiza el punto para hacer referencia al valor de las instrucciones with:

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

Variables

Las variables del texto/plantilla deben crearse dentro de la plantilla. Por ejemplo, para crear una variable llamada $variable con el valor actual de punto, escribiría lo siguiente:

{{ $variable := . }}

Puede usar $variable dentro de un rango o with y hará referencia al valor del punto en el momento en que se definió la variable, no al valor actual del punto.

Por ejemplo, no puede escribir una plantilla que use {{ .Labels }} en el segundo rango porque aquí el punto hace referencia a la etiqueta actual, no a la alerta actual:

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

Para solucionar este problema, defina una variable llamada $alert en el primer rango y antes del segundo rango:

{{ 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 con índice

Para poder obtener el índice de cada alerta de un rango, defina las variables de índice y valor al principio del rango:

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

Definición de plantillas

Puede definir plantillas que se puedan usar en de otras plantillas mediante define y el nombre de la plantilla entre comillas dobles. No debe definir plantillas con el mismo nombre que otras plantillas, incluidas las plantillas predeterminadas, como __subject, __text_values_list, __text_alert_list, default.title y default.message. Si se ha creado una plantilla con el mismo nombre que una plantilla predeterminada, o una plantilla en otra plantilla de notificaciones, Grafana puede utilizar cualquiera de las dos. Grafana no impide ni muestra ningún mensaje de error cuando hay dos o más plantillas con el mismo nombre.

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

Ejecución de plantillas

Puede ejecutar una plantilla definida en su plantilla mediante template, el nombre de la plantilla entre comillas dobles y el cursor que se debe pasar a la plantilla:

{{ template "print_labels" . }}

Paso de datos a las plantillas

En una plantilla, un punto hace referencia al valor que se pasa a la plantilla.

Por ejemplo, si a una plantilla se le pasa una lista de alertas de activación, el punto se refiere a esa lista de alertas de activación:

{{ template "print_alerts" .Alerts }}

Si a la plantilla se le pasan las etiquetas ordenadas de una alerta, el punto hace referencia a la lista de etiquetas ordenadas:

{{ template "print_labels" .SortedLabels }}

Resulta útil a la hora de escribir plantillas reutilizables. Por ejemplo, para imprimir todas las alertas, puede escribir lo siguiente:

{{ template "print_alerts" .Alerts }}

Luego, para imprimir solo las alertas de activación, puede escribir lo siguiente:

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

Esto funciona porque .Alerts y .Alerts.Firing son listas de alertas.

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

Comentarios

Puede agregar comentarios con {{/* y */}}:

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

Para evitar que los comentarios agreguen saltos de línea, utilice:

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

Sangría

Puede usar sangrías, tanto tabulaciones como espacios, y saltos de línea para que las plantillas sean más legibles:

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

Sin embargo, la sangría de la plantilla también estará presente en el texto. A continuación, veremos cómo eliminarlo.

Eliminación de espacios y saltos de línea

En el texto/plantilla, use {{- y -}} para eliminar los espacios iniciales y finales y los saltos de línea.

Por ejemplo, cuando se utilizan sangrías y saltos de línea para hacer que una plantilla sea más legible:

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

La sangría y los saltos de línea también estarán presentes en el texto:

    alertname = "Test"

    grafana_folder = "Test alerts"

Para poder eliminar las sangrías y los saltos de línea del texto, cambie }} por -}} al principio de cada rango:

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

Las sangrías y los saltos de línea de la plantilla ya no aparecen en el texto:

alertname = "Test"
grafana_folder = "Test alerts"