Creación de plantillas de etiquetas y anotaciones

Este tema de documentación está diseñado para los espacios de trabajo de Grafana que admiten la versión 10.x de Grafana.

Para ver los espacios de trabajo de Grafana que admiten la versión 9.x de Grafana, consulte. Trabajando en Grafana versión 9

Para ver los espacios de trabajo de Grafana que admiten la versión 8.x de Grafana, consulte. Trabajando en Grafana versión 8

Puede usar plantillas para incluir datos de consultas y expresiones en etiquetas y anotaciones. Por ejemplo, es posible que desee establecer la etiqueta de gravedad de una alerta en función del valor de la consulta o utilizar la etiqueta de instancia de la consulta en una anotación resumida para saber qué servidor está haciendo un uso elevado de la CPU.

Todas las plantillas deben escribirse en texto o plantilla. Independientemente de si está creando una plantilla para una etiqueta o una anotación, debe escribir cada plantilla en línea dentro de la etiqueta o anotación que esté creando la plantilla. Esto significa que no puede compartir plantillas entre etiquetas y anotaciones, sino que tendrá que copiar las plantillas donde quiera usarlas.

Cada plantilla se evalúa siempre que se evalúa la regla de alerta y se evalúa para cada alerta por separado. Por ejemplo, si la regla de alerta tiene una anotación resumida basada en una plantilla y la regla de alerta tiene 10 alertas de activación, la plantilla se ejecutará 10 veces, una para cada alerta. En la medida de lo posible, debe intentar evitar realizar cálculos costosos en sus plantillas.

Ejemplos

En lugar de escribir un tutorial completo sobre el texto o la plantilla, los siguientes ejemplos intentan mostrar los casos de uso más comunes que hemos visto en el caso de las plantillas. Puedes usar estos ejemplos textualmente o adaptarlos según sea necesario para tu caso de uso. Para obtener más información sobre cómo escribir un texto/plantilla, consulta la documentación del texto/plantilla.

Imprima todas las etiquetas, separadas por comas

Para imprimir todas las etiquetas, separadas por comas, imprima la $labels variable:

{{ $labels }}

Por ejemplo, si aparece una alerta con las etiquetasalertname=High CPU usage, grafana_folder=CPU alerts se imprimiría: instance=server1

alertname=High CPU usage, grafana_folder=CPU alerts, instance=server1

nota

Si utiliza condiciones clásicas, no $labels contendrá ninguna etiqueta de la consulta. Consulte la variable $labels para obtener más información.

Imprima todas las etiquetas, una por línea

Para imprimir todas las etiquetas, una por línea, utilice range a para iterar cada par clave/valor e imprímalas individualmente. Aquí $k se refiere al nombre y $v al valor de la etiqueta actual:

{{ range $k, $v := $labels -}}
{{ $k }}={{ $v }}
{{ end }}

Por ejemplo, si aparece una alerta con las etiquetasalertname=High CPU usage, grafana_folder=CPU alerts se imprimiría lo siguiente: instance=server1

alertname=High CPU usage
grafana_folder=CPU alerts
instance=server1

nota

Si utiliza condiciones clásicas, no $labels contendrá ninguna etiqueta de la consulta. Consulte la variable $labels para obtener más información.

Imprima una etiqueta individual

Para imprimir una etiqueta individual, utilice la index función con la $labels variable:

The host {{ index $labels "instance" }} has exceeded 80% CPU usage for the last 5 minutes

Por ejemplo, si aparece una alerta con la etiquetainstance=server1, se imprimiría:

The host server1 has exceeded 80% CPU usage for the last 5 minutes

nota

Si utiliza condiciones clásicas, no $labels contendrá ninguna etiqueta de la consulta. Consulte la variable $labels para obtener más información.

Imprime el valor de una consulta

Para imprimir el valor de una consulta instantánea, puede imprimir su identificador de referencia mediante la index función y la $values variable:

{{ index $values "A" }}

Por ejemplo, si una consulta instantánea devuelve el valor 81.2345, se imprimirá:

81.2345

Para imprimir el valor de una consulta de rango, primero debe reducirla de una serie temporal a un vector instantáneo con una expresión reducida. A continuación, puede imprimir el resultado de la expresión reducida utilizando su identificador de referencia en su lugar. Por ejemplo, si la expresión reducida toma el promedio de A y tiene el ID de referencia B, escribiría:

{{ index $values "B" }}

Imprime el valor humanizado de una consulta

Para imprimir el valor humanizado de una consulta instantánea, utilice la humanize función:

{{ humanize (index $values "A").Value }}

Por ejemplo, si se trata de una consulta instantánea que devuelva el valor 81.2345, se imprimirá:

81.234

Para imprimir el valor humanizado de una consulta de rango, primero debe reducirlo de una serie temporal a un vector instantáneo con una expresión reducida. A continuación, puede imprimir el resultado de la expresión reducida utilizando su identificador de referencia en su lugar. Por ejemplo, si la expresión reducida toma el promedio de A y tiene el ID de referencia B, escribiría:

{{ humanize (index $values "B").Value }}

Imprima el valor de una consulta como porcentaje

Para imprimir el valor de una consulta instantánea como porcentaje, utilice la humanizePercentage función:

{{ humanizePercentage (index $values "A").Value }}

Esta función espera que el valor sea un número decimal entre 0 y 1. Si, por el contrario, el valor es un número decimal entre 0 y 100, puede dividirlo entre 100 en la consulta o mediante una expresión matemática. Si la consulta es una consulta de rango, primero debe reducirla de una serie temporal a un vector instantáneo con una expresión reducida.

Establezca una gravedad a partir del valor de una consulta

Para establecer una etiqueta de gravedad a partir del valor de una consulta, utilice una sentencia if y la función de comparación mayor que. Asegúrese de utilizar decimales (80.0,,, etc.) al realizar comparaciones 50.00.0, $values ya que el texto o la plantilla no admiten la coerción de tipos. Puedes encontrar una lista de todas las funciones de comparación compatibles aquí.

{{ if (gt $values.A.Value 80.0) -}}
high
{{ else if (gt $values.A.Value 50.0) -}}
medium
{{ else -}}
low
{{- end }}

Imprima todas las etiquetas a partir de un estado clásico

No puede utilizarlas $labels para imprimir etiquetas a partir de la consulta si utiliza las condiciones clásicas y debe utilizarlas $values en su lugar. Esto se debe a que las condiciones clásicas descartan estas etiquetas para imponer un comportamiento unidimensional (como máximo una alerta por regla de alerta). Si las condiciones clásicas no descartaban estas etiquetas, las consultas que devolvían varias series temporales hacían que las alertas oscilaran entre activarse y resolverse constantemente, ya que las etiquetas cambiaban cada vez que se evaluaba la regla de alerta.

En cambio, la $values variable contiene los valores reducidos de todas las series temporales para todas las condiciones que se estén activando. Por ejemplo, si tiene una regla de alerta con una consulta A que devuelve dos series temporales y una condición B clásica con dos condiciones, $values contendrá B0B1, B2 yB3. Si la condición clásica B tuviera solo una condición, $values contendría solo B0 yB1.

Para imprimir todas las etiquetas de todas las series temporales de activación, utilice la siguiente plantilla (asegúrese de sustituir B la expresión regular por el identificador de referencia de la condición clásica si es diferente):

{{ range $k, $v := $values -}}
{{ if (match "B[0-9]+" $k) -}}
{{ $k }}: {{ $v.Labels }}{{ end }}
{{ end }}

Por ejemplo, una condición clásica para dos series temporales que superen una sola condición imprimiría:

B0: instance=server1
B1: instance=server2

Si la condición clásica tiene dos o más condiciones y una serie temporal supera varias condiciones al mismo tiempo, sus etiquetas se duplicarán para cada condición que se supere:

B0: instance=server1
B1: instance=server2
B2: instance=server1
B3: instance=server2

Si necesita imprimir etiquetas únicas, debería considerar la posibilidad de cambiar las reglas de alerta de unidimensionales a multidimensionales. Puedes hacerlo sustituyendo la condición clásica por expresiones de reducción y matemáticas.

Imprime todos los valores de una condición clásica

Para imprimir todos los valores de una condición clásica, tome el ejemplo anterior y $v.Labels sustitúyalos por$v.Value:

{{ range $k, $v := $values -}}
{{ if (match "B[0-9]+" $k) -}}
{{ $k }}: {{ $v.Value }}{{ end }}
{{ end }}

Por ejemplo, una condición clásica para dos series temporales que superen una sola condición imprimiría:

B0: 81.2345
B1: 84.5678

Si la condición clásica tiene dos o más condiciones y una serie temporal supera varias condiciones al mismo tiempo, $values contendrá los valores de todas las condiciones:

B0: 81.2345
B1: 92.3456
B2: 84.5678
B3: 95.6789

Variables

Al crear plantillas de etiquetas y anotaciones, tiene a su disposición las siguientes variables:

La variable de etiquetas

La $labels variable contiene todas las etiquetas de la consulta. Por ejemplo, supongamos que tiene una consulta que devuelve el uso de la CPU de todos los servidores y tiene una regla de alerta que se activa cuando alguno de los servidores ha superado el 80% de uso de la CPU durante los últimos 5 minutos. Desea agregar una anotación resumida a la alerta que indique qué servidor está experimentando un uso elevado de la CPU. Con la $labels variable, puede escribir una plantilla que imprima una oración legible por humanos, como:

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes

nota

Si está utilizando una condición clásica, no $labels contendrá ninguna etiqueta de la consulta. Las condiciones clásicas descartan estas etiquetas para imponer un comportamiento unidimensional (como máximo una alerta por regla de alerta). Si quieres usar las etiquetas de la consulta en tu plantilla, sigue el ejemplo anterior de Imprimir todas las etiquetas a partir de una condición clásica.

La variable de valor

La $value variable es una cadena que contiene las etiquetas y los valores de todas las consultas instantáneas, las expresiones de umbral, reducción y matemáticas, y las condiciones clásicas de la regla de alerta. No contiene los resultados de las consultas de rango, ya que pueden devolver entre 10 y 10 000 filas o métricas. Si lo hiciera, para consultas especialmente grandes, una sola alerta podría consumir decenas de MB de memoria y Grafana se quedaría sin memoria muy rápidamente.

Para imprimir la $value variable en el resumen, escribiría algo como esto:

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ $value }}

Y se vería más o menos así:

CPU usage for instance1 has exceeded 80% for the last 5 minutes: [ var='A' labels={instance=instance1} value=81.234 ]

Aquí var='A' se refiere a la consulta instantánea con el identificador de labels={instance=instance1} referencia A, a las etiquetas y value=81.234 al uso medio de la CPU en los últimos 5 minutos.

Si desea imprimir solo una parte de la cadena en lugar de la cadena completa, utilice la $values variable. Contiene la misma información que$value, pero en una tabla estructurada, y es mucho más fácil de usar que escribir una expresión regular para que coincida solo con el texto deseado.

La variable de valores

La $values variable es una tabla que contiene las etiquetas y los valores de punto flotante de todas las consultas y expresiones instantáneas, indexadas por sus identificadores de referencia.

Para imprimir el valor de la consulta instantánea con el ID de referencia A:

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "A" }}

Por ejemplo, en el caso de una alerta con las etiquetas instance=server1 y una consulta instantánea con el valor81.2345, se imprimiría:

CPU usage for instance1 has exceeded 80% for the last 5 minutes: 81.2345

Si la consulta en el ID de referencia A es una consulta de rango en lugar de una consulta instantánea, agrega una expresión reducida con el ID de referencia B y (index $values "A") sustitúyela por(index $values "B"):

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "B" }}

Funciones

Al crear plantillas de etiquetas y anotaciones, tiene a su disposición las siguientes funciones:

argumentos

La args función traduce una lista de objetos a un mapa con las claves arg0, arg1, etc. El objetivo es permitir que se pasen varios argumentos a las plantillas.

{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}

1 2

URL externa

La externalURL función devuelve la URL externa del servidor Grafana.

{{ externalURL }}

https://example.com/grafana

GraphLink

La graphLink función devuelve la ruta a la vista gráfica Explora en Grafana versión 10 para la expresión y la fuente de datos dadas.

{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}

/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]

humanizar

La humanize función humaniza los números decimales.

{{ humanize 1000.0 }}

1k

humaniza 1024

humanize1024Funciona de manera similarhumanize, pero usa 1024 como base en lugar de 1000.

{{ humanize1024 1024.0 }}

1ki

Humaniza la duración

La humanizeDuration función humaniza una duración en segundos.

{{ humanizeDuration 60.0 }}

1m 0s

Humaniza el porcentaje

La humanizePercentage función humaniza un valor de proporción a un porcentaje.

{{ humanizePercentage 0.2 }}

20%

Humaniza la marca de tiempo

La humanizeTimestamp función humaniza una marca de tiempo de Unix.

{{ humanizeTimestamp 1577836800.0 }}

2020-01-01 00:00:00 +0000 UTC

partido

La match función compara el texto con un patrón de expresión regular.

{{ match "a.*" "abc" }}

true

Prefijo de ruta

La pathPrefix función devuelve la ruta del servidor Grafana.

{{ pathPrefix }}

/grafana

TableLink

La tableLink función devuelve la ruta a la vista tabular Explora en Grafana versión 10 para la expresión y la fuente de datos determinadas.

{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}

/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]

title

La title función pone en mayúscula el primer carácter de cada palabra.

{{ title "hello, world!" }}

Hello, World!

A Lower

La toLower función devuelve todo el texto en minúsculas.

{{ toLower "Hello, world!" }}

hello, world!

a Toupper

La toUpper función devuelve todo el texto en mayúsculas.

{{ toUpper "Hello, world!" }}

HELLO, WORLD!

reReplaceAll

La reReplaceAll función reemplaza el texto que coincide con la expresión regular.

{{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}

example.com:8080