Plantillas y variables

Una variable es un marcador de posición para un valor. Puede utilizar variables en las consultas de métricas y en los títulos de los paneles. Las variables le permiten crear paneles de control más interactivos y dinámicos. En lugar de codificar de forma rígida elementos como los nombres de servidores, aplicaciones y sensores en las consultas de métricas, puede utilizar variables en su lugar.

Las variables se muestran como listas desplegables en la parte superior del panel de control. Al cambiar el valor mediante la lista desplegable situada en la parte superior del panel, las consultas de métricas del panel reflejan el nuevo valor.

Pueden resultar especialmente útiles para los administradores que quieren permitir a los visualizadores ajustar las visualizaciones rápidamente, pero no quieren concederles permisos de edición completos. Los visualizadores de Grafana pueden utilizar variables.

Al utilizar variables y plantillas, puede gestionar paneles de un único origen. Si tiene varios orígenes de datos o servidores idénticos, puede crear un panel de control y utilizar variables para cambiar lo que está viendo. Esto simplifica el mantenimiento y la conservación.

Para obtener una lista de los tipos de variables admitidos y las instrucciones para agregar cada tipo de variable, consulte Tipos de variables.

Plantillas

Una plantilla es cualquier consulta que contiene una variable.

Por ejemplo, si administrara un panel para supervisar varios servidores, podría crear un panel para cada servidor. O puede crear un panel y utilizar paneles con consultas de plantilla, como se muestra en el siguiente ejemplo.

wmi_system_threads{instance=~"$server"}

Los valores de las variables siempre se sincronizan con la URL mediante la sintaxis var-<varname>=value.

Prácticas recomendadas de variables

Las listas desplegables de variables se muestran en el orden en que aparecen en la lista de variables de Configuración del panel.

Coloque las variables que cambiará con frecuencia en la parte superior, de modo que se muestren primero, en el extremo izquierdo del panel.

Sintaxis de variable

Los títulos de los paneles y las consultas de las métricas pueden ver las variables mediante dos sintaxis distintas:

Antes de enviar las consultas al origen de datos, la consulta se interpola, lo que significa que la variable se reemplaza por su valor actual. Durante la interpolación, es posible que el valor de la variable se escape para ajustarlo a la sintaxis del lenguaje de consulta y al lugar en el que se utiliza. Por ejemplo, una variable que se utilice en una expresión regular en una consulta de Prometheus tendrá un escape de expresiones regulares. Consulte el tema de la documentación específico del origen de datos para obtener más información sobre el escape de valores durante la interpolación.

Para obtener información sobre la sintaxis avanzada para anular el formato predeterminado del origen de datos, consulte Opciones avanzadas de formato de variables.

Otras opciones de variables

En esta sección se explican las otras opciones de variables disponibles.

Introducción de opciones de selección de variables

Puede utilizar Opciones de selección para gestionar las selecciones de opciones variables. Todas las opciones de selección son opcionales y están desactivadas de forma predeterminada.

Varios valores

Si activa esta opción, la lista desplegable de variables permite seleccionar varias opciones al mismo tiempo. Para obtener más información, consulte Formateo de variables de varios valores.

Opción Incluir todo

El espacio de trabajo de Grafana agrega una opción All a la lista desplegable de variables. Si un usuario final selecciona esta opción, se seleccionan todas las opciones variables.

Valor Personalizar todo

Esta opción solo está visible si se selecciona Opción Incluir todo.

Para definir el valor de la opción All, ingrese una de sintaxis de expresión regular, global o Lucene en el campo Valor Personalizar todo.

De forma predeterminada, el valor All incluye todas las opciones de la expresión combinada. Puede llegar a ser muy largo y provocar problemas de rendimiento. A veces, puede ser mejor especificar un valor Personalizar todo, como una expresión regular comodín.

Al utilizar la sintaxis de expresión regular, global o Lucene en la opción Valor Personalizar todo, nunca se aplica escape, por lo que debe tener en cuenta qué valor es válido para el origen de datos.

Opciones avanzadas de formato de variables

El formato de la interpolación de variables depende del origen de datos, pero hay algunas situaciones en las que es posible que quiera cambiar el formato predeterminado.

Por ejemplo, el valor predeterminado del origen de datos de MySQL es unir varios valores separados por comas entre comillas: 'server01','server02'. En algunos casos, es posible que quiera que haya una cadena separada por comas sin comillas: server01,server02. Para ello, utilice las siguientes opciones avanzadas para el formato de variables.

Sintaxis general

Sintaxis: ${var_name:option}

Si se especifica alguna opción de formato no válida, glob es la opción predeterminada o alternativa.

CSV

Formatea las variables con varios valores como una cadena separada por comas.

servers = ['test1', 'test2']
String to interpolate: '${servers:csv}'
Interpolation result: 'test1,test2'

Distribuida: OpenTSDB

Formatea las variables con varios valores en un formato personalizado para OpenTSDB.

servers = ['test1', 'test2']
String to interpolate: '${servers:distributed}'
Interpolation result: 'test1,servers=test2'

Doublequote

Formatea las variables de un solo valor y de varios valores en una cadena separada por comas, aplica escape a " en cada valor por \" y cita cada valor con ".

servers = ['test1', 'test2']
String to interpolate: '${servers:doublequote}'
Interpolation result: '"test1","test2"'

Glob: Graphite

Formatea las variables con varios valores en un patrón glob (para consultas de Graphite).

servers = ['test1', 'test2']
String to interpolate: '${servers:glob}'
Interpolation result: '{test1,test2}'

JSON

Formatea las variables con varios valores como una cadena separada por comas.

servers = ['test1', 'test2']
String to interpolate: '${servers:json}'
Interpolation result: '["test1", "test2"]'

Lucene: OpenSearch

Formatea las variables con varios valores en formato Lucene para OpenSearch.

servers = ['test1', 'test2']
String to interpolate: '${servers:lucene}'
Interpolation result: '("test1" OR "test2")'

Percentencode

Formatea las variables de un solo valor y de varios valores para utilizarlas en los parámetros de URL.

servers = ['foo()bar BAZ', 'test2']
String to interpolate: '${servers:percentencode}'
Interpolation result: 'foo%28%29bar%20BAZ%2Ctest2'

Canalización

Formatea las variables con varios valores en una cadena separada por canalizaciones.

servers = ['test1.', 'test2']
String to interpolate: '${servers:pipe}'
Interpolation result: 'test1.|test2'

Raw

Desactiva el formato específico del origen de datos, como las comillas simples en una consulta SQL.

servers = ['test1.', 'test2']
String to interpolate: '${var_name:raw}'
Interpolation result: '{test.1,test2}'

Regex

Formatea las variables con varios valores en una cadena de expresiones regulares.

servers = ['test1.', 'test2']
String to interpolate: '${servers:regex}'
Interpolation result: '(test1\.|test2)'

Singlequote

Formatea las variables de uno o varios valores en una cadena separada por comas, escapa ' en cada valor por \' y cita cada valor con'.

servers = ['test1', 'test2']
String to interpolate: '${servers:singlequote}'
Interpolation result: "'test1','test2'"

Sqlstring

Formatea las variables de uno o varios valores en una cadena separada por comas, escapa ' en cada valor por '' y cita cada valor con'.

servers = ["test'1", "test2"]
String to interpolate: '${servers:sqlstring}'
Interpolation result: "'test''1','test2'"

Text

Formatea las variables de un solo valor y de varios valores para incluirlas en su representación textual. Para una sola variable, simplemente devolverá la representación de texto. Para las variables con varios valores, devolverá la representación de texto combinada con +.

servers = ["test1", "test2"]
String to interpolate: '${servers:text}'
Interpolation result: "test1 + test2"

Formateo de variables de varios valores

Interpolar una variable con varios valores seleccionados es complicado, ya que no es fácil formatear los múltiples valores en una cadena que sea válida en el contexto dado en el que se usa la variable. Grafana intenta resolver esto al permitir que cada complemento de origen de datos informe al motor de interpolación de plantillas qué formato usar para varios valores.

Variables de valores múltiples con un origen de datos de Graphite

Graphite usa expresiones globales. En este caso, una variable con varios valores se interpolaría como {host1,host2,host3} si el valor de la variable actual fuera host1, host2 y host3.

Variables de varios valores con un origen de datos de Prometheus o InfluxDB

InfluxDB y Prometheus utilizan expresiones regulares, por lo que se interpolaría la misma variable que (host1|host2|host3). También se aplicaría escape de expresiones regulares a cada valor. De lo contrario, un valor con un carácter de control de expresión regular rompería la expresión regular.

Variables de varios valores con un origen de datos elástico

Amazon OpenSearch utiliza la sintaxis de consulta de Lucene, por lo que se formatearía la misma variable como ("host1" OR "host2" OR "host3"). En este caso, se debe aplicar escape a todos los valores, para que el valor solo contenga comillas y palabras de control de Lucene.

Solución de problemas de formateo

La aplicación de escape y el formateo automáticos pueden provocar problemas. Puede resultar complicado comprender la lógica detrás de un problema, especialmente en el caso de InfluxDB y Prometheus, donde el uso de la sintaxis de expresiones regulares requiere que la variable se utilice en el contexto de un operador de expresiones regulares.

Si no desea que Grafana escape y formatee expresiones regulares de forma automática, debe llevar a cabo una de estas acciones:

Filtrado de variables con expresiones regulares

Con la opción Consulta de expresiones regulares, se puede filtrar la lista de opciones que devuelve la consulta de variables o modificar las opciones devueltas.

En esta sección, se muestra cómo utilizar las expresiones regulares para filtrar y modificar los valores de la lista desplegable de variables.

Con la opción Consulta de expresiones regulares, se filtra la lista de opciones devuelta por la consulta de variables o se modifican las opciones devueltas. Para más información, consulte Regular expressions.

A continuación, se muestran algunos ejemplos de filtrado en la lista de opciones:

backend_01
backend_02
backend_03
backend_04

Filtrado para que se devuelvan solo las opciones que terminan en 01 o 02

Expresión regular:

/.*[01|02]/

Resultado:

backend_01
backend_02

Filtrado y modificación de las opciones mediante un grupo de captura de expresiones regulares para devolver parte del texto

Expresión regular:

/.*(01|02)/

Resultado:

01
02

Filtrado y modificación: ejemplo de Prometheus

Lista de opciones:

up{instance="demo.robustperception.io:9090",job="prometheus"} 1 1521630638000
up{instance="demo.robustperception.io:9093",job="alertmanager"} 1 1521630638000
up{instance="demo.robustperception.io:9100",job="node"} 1 1521630638000

Expresión regular:

/.*instance="([^"]*).*/

Resultado:

demo.robustperception.io:9090
demo.robustperception.io:9093
demo.robustperception.io:9100

Filtrado y modificación mediante grupos de captura de valores y texto con nombre asignado

Al utilizar grupos de captura con nombre asignado, puede capturar partes independientes de “texto” y “valor” de las opciones que devuelve la consulta de variables. La lista desplegable de variables puede contener un nombre descriptivo para cada valor que se pueda seleccionar.

Por ejemplo, al consultar la métrica node_hwmon_chip_names de Prometheus, chip_name es más simple que el valor de chip. Comience con el siguiente resultado de consulta variables.

node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_0",chip_name="enp216s0f0np0"} 1
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_1",chip_name="enp216s0f0np1"} 1
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_2",chip_name="enp216s0f0np2"} 1
node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_3",chip_name="enp216s0f0np3"} 1

Pásela por la siguiente expresión regular.

/chip_name="(?<text>[^"]+)|chip="(?<value>[^"]+)/g

Se produce la siguiente lista desplegable.

Display Name          Value
------------          -------------------------
enp216s0f0np0         0000:d7:00_0_0000:d8:00_0
enp216s0f0np1         0000:d7:00_0_0000:d8:00_1
enp216s0f0np2         0000:d7:00_0_0000:d8:00_2
enp216s0f0np3         0000:d7:00_0_0000:d8:00_3

Nota: Solo se admiten los nombres de los grupos de captura text y value.

Paneles o filas que se repiten

Puede crear paneles dinámicos mediante variables de plantillas. Todas las variables de las consultas se amplían hasta el valor actual de la variable antes de que la consulta se envíe a la base de datos. Con las variables, puede reutilizar un único panel para todos los servicios.

Las variables de plantillas pueden resultar muy útiles para cambiar dinámicamente las consultas en todo un panel. Si quiere que Grafana cree dinámicamente nuevos paneles o filas en función de los valores que seleccionó, puede utilizar la característica Repetir.

Paneles que se repiten

Si tiene una variable con las opciones Multi-value o Include all value activadas, puede elegir un panel y hacer que Grafana repita ese panel para cada valor seleccionado. Puede encontrar la característica Repetir en la pestaña General en el modo de edición de paneles.

direction controla la disposición de los paneles.

Si elige horizontal, los paneles se disponen uno al lado del otro. Grafana ajusta automáticamente el ancho de cada panel repetido para que se llene toda la fila. Actualmente, no se pueden combinar otros paneles de una fila con un panel repetido.

Establezca Max per row para indicarle a Grafana cuántos paneles por fila quiere como máximo. El valor predeterminado es 4.

Si elige vertical, los paneles se disponen de arriba a abajo en una columna. El ancho de los paneles repetidos es el mismo que el del primer panel (la plantilla original) que se repite.

Haga cambios únicamente en el primer panel (la plantilla original). Para que los cambios surtan efecto en todos los paneles, debe iniciar una recreación dinámica del panel. Para ello, puede cambiar el valor de la variable (es decir, la base de la repetición) o volver a cargar el panel.

Filas que se repiten

Como se ha visto anteriormente, con los paneles, también puede repetir filas si tiene variables establecidas con la opción de selección Multi-value o Include all value.

Para activar esta característica, debe agregar antes una nueva Fila mediante el menú Agregar panel. A continuación, haga una pausa en el título de la fila y pulse el botón de engranaje para acceder al panel de configuración Row Options. A continuación, puede seleccionar la variable para repetir la fila.

Se recomienda utilizar también una variable en el título de la fila.