Modelos e variáveis

Uma variável é um espaço reservado para um valor. Você pode usar variáveis em consultas de métricas e em títulos de painéis. As variáveis permitem criar dashboards mais interativos e dinâmicos. Em vez da codificação rígida dos nomes de servidores, das aplicações e dos sensores em suas consultas de métricas, você pode usar variáveis no lugar deles.

As variáveis são exibidas como listas suspensas na parte superior do dashboard. Quando você altera o valor usando a lista suspensa na parte superior do dashboard, as consultas de métricas do seu painel refletem o novo valor.

Eles podem ser especialmente úteis para administradores que desejam permitir que os visualizadores ajustem as visualizações rapidamente, mas que não desejam conceder a eles permissões completas de edição. Os visualizadores do Grafana podem usar variáveis.

Ao usar variáveis e modelos, você pode criar dashboards de origem única. Se você tiver várias fontes de dados ou servidores idênticos, poderá criar um dashboard e usar variáveis para alterar o que está visualizando. Isso simplifica a manutenção e conservação.

Para obter uma lista dos tipos de variáveis compatíveis e instruções para adicionar cada tipo de variável, consulte Tipos de variáveis.

Modelos

Um modelo é qualquer consulta que contém uma variável.

Por exemplo, se você estivesse administrando um dashboard para monitorar vários servidores, você poderia criar um dashboard para cada servidor. Ou você poderia criar um dashboard e usar painéis com consultas de modelos, como mostrado no exemplo a seguir.

wmi_system_threads{instance=~"$server"}

Os valores das variáveis são sempre sincronizados com o URL usando a sintaxe var-<varname>=value.

Práticas recomendadas de variáveis

As listas suspensas de variáveis são exibidas na ordem em que estão listadas na lista de variáveis em Configurações do dashboard.

Coloque as variáveis que você vai alterar com frequência na parte superior para que elas sejam mostradas primeiro, na extremidade esquerda do dashboard.

Sintaxe da variável

Os títulos dos painéis e as consultas métricas podem ver variáveis usando duas sintaxes diferentes:

Antes que as consultas sejam enviadas à fonte de dados, a consulta é interpolada, o que significa que a variável é substituída pelo seu valor atual. Durante a interpolação, o valor da variável pode ser de escape para se adequar à sintaxe da linguagem de consulta e onde ela é usada. Por exemplo, uma variável usada em uma expressão regex em uma consulta do Prometheus terá escape de regex. Leia o tópico da documentação específica da fonte de dados para obter detalhes sobre o escape de valor durante a interpolação.

Para obter informações sobre a sintaxe avançada para substituir a formatação padrão da fonte de dados, consulte Opções avançadas de formato de variáveis.

Outras opções de variáveis

Esta seção explica as outras opções de variáveis disponíveis.

Inserir opções de seleção de variáveis

Você pode usar as Opções de seleção para gerenciar as seleções de opções variáveis. Todas as opções de seleção são opcionais e estão desativadas por padrão.

Vários valores

Se você ativar esta opção, a lista suspensa de variáveis será compatível com a seleção de várias opções ao mesmo tempo. Para ter mais informações, consulte Formatação de variáveis de vários valores.

Incluir todas as opções

O espaço de trabalho do Grafana adiciona uma opção All à lista suspensa de variáveis. Se um usuário final selecionar esta opção, todas as opções de variáveis serão selecionadas.

Personalizar todos os valores

Esta opção estará visível somente se a opção Incluir tudo estiver selecionada.

Para definir o valor da opção All, insira a sintaxe regex, glob ou Lucene no campo Personalizar todos os valores.

Por padrão, o valor All inclui todas as opções em uma expressão combinada. Isso pode se tornar muito longo e causar problemas de performance. Às vezes, pode ser melhor especificar um valor personalizado para todos, como um regex curinga.

Quando você usa a sintaxe personalizada regex, glob ou Lucene na opção Personalizar todos os valores, ela nunca é de escape, então você deve considerar qual é um valor válido para a fonte de dados.

Opções avançadas de formato de variáveis

A formatação da interpolação de variável depende da fonte de dados, mas há algumas situações em que talvez você queira alterar a formatação padrão.

Por exemplo, o padrão para a fonte de dados MySQL é unir vários valores separados por vírgula com aspas: 'server01','server02'. Em alguns casos, você pode desejar ter uma string separada por vírgulas sem aspas: server01,server02. Para fazer isso, use as opções avançadas de formatação de variáveis a seguir.

Sintaxe geral

Sintaxe: ${var_name:option}

Se alguma opção de formatação inválida for especificada, glob será a opção padrão ou de fallback.

CSV

Formata variáveis com vários valores como uma string separada por vírgulas.

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

Distribuído - OpenTSDB

Formata variáveis com vários valores em formato personalizado para OpenTSDB.

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

Doublequote

Formata variáveis de valor único e de vários valores em uma string separada por vírgula, escapa " em cada valor por \" e cita cada valor com ".

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

Glob - Graphite

Formata variáveis com vários valores em um glob (para consultas do Graphite).

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

JSON

Formata variáveis com vários valores como uma string separada por vírgulas.

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

Lucene - OpenSearch

Formata variáveis com vários valores no formato Lucene para OpenSearch.

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

Percentencode

Formata variáveis de valor único e de vários valores para uso em parâmetros de URL.

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

Barra vertical

Formata variáveis com vários valores como uma string separada por barras verticais.

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

Raw

Desativa a formatação específica da fonte de dados, como aspas simples em uma consulta SQL.

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

Regex

Formata variáveis com vários valores como uma string regex.

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

Singlequote

Formata variáveis de valor único e de vários valores em uma string separada por vírgula, escapa ' em cada valor por \' e cita cada valor com '.

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

Sqlstring

Formata variáveis de valor único e de vários valores em uma string separada por vírgula, escapa ' em cada valor por '' e cita cada valor com '.

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

Texto

Formata variáveis de valor único e de vários valores em sua representação de texto. Para uma única variável, ele retornará apenas a representação do texto. Para variáveis de vários valores, ele retornará a representação de texto combinada com +.

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

Formatação de variáveis de vários valores

Interpolar uma variável com vários valores selecionados é complicado, pois não é simples formatar os vários valores em uma string válida no contexto em que a variável é usada. O Grafana tenta resolver isso permitindo que cada plug-in de fonte de dados informe ao mecanismo de interpolação de modelos qual formato usar para vários valores.

Variáveis de vários valores com uma fonte de dados Graphite

O Graphite usa expressões globais. Uma variável com vários valores seria, nesse caso, interpolada como {host1,host2,host3} se o valor da variável atual fosse host1, host2 e host3.

Variáveis de vários valores com uma fonte de dados Prometheus ou InfluxDB

O InfluxDB e o Prometheus usam expressões regex, então a mesma variável seria interpolada como (host1|host2|host3). Cada valor também teria escape de regex. Caso contrário, um valor com um caractere de controle regex quebraria a expressão regex.

Variáveis de vários valores com uma fonte de dados elástica

O Amazon OpenSearch usa a sintaxe de consulta do Lucene, então a mesma variável seria formatada como ("host1" OR "host2" OR "host3"). Nesse caso, todo valor deve ser de escape para que o valor contenha apenas palavras de controle e aspas do Lucene.

Solucionar problemas de formatação

O escape e a formatação automáticos podem causar problemas. Pode ser difícil entender a lógica por trás de um problema, especialmente para InfluxDB e Prometheus, em que o uso da sintaxe regex exige que a variável seja usada no contexto do operador regex.

Se você não quiser que o Grafana faça esse escape e formatação automáticos de regex, você pode fazer uma das seguintes opções:

Filtrar variáveis com regex

Usando a opção de consulta regex, você pode filtrar a lista de opções retornadas pela consulta da variável ou modificar as opções retornadas.

Esta seção mostra como usar o regex para filtrar e modificar valores na lista suspensa de variáveis.

Usando a opção de consulta regex, você filtra a lista de opções retornadas pela consulta da variável ou modifica as opções retornadas. Para obter mais informações, consulte Expressões regulares.

Exemplos de filtragem na seguinte lista de opções:

backend_01
backend_02
backend_03
backend_04

Filtragem para que somente as opções que terminam com 01 ou 02 sejam retornadas

Regex:

/.*[01|02]/

Resultado:

backend_01
backend_02

Filtrar e modificar as opções usando um grupo de captura de regex para retornar parte do texto

Regex:

/.*(01|02)/

Resultado:

01
02

Filtrar e modificar | Exemplo do Prometheus

Lista de opções:

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

Regex:

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

Resultado:

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

Filtrar e modificar usando grupos nomeados de captura de texto e valor

Usando grupos de captura nomeados, você pode capturar partes separadas de “texto” e “valor” das opções retornadas pela consulta da variável. A lista suspensa de variáveis pode conter um nome amigável para cada valor que pode ser selecionado.

Por exemplo, ao consultar a métrica node_hwmon_chip_names do Prometheus, chip_name é mais amigável do que o valor chip. Comece com o resultado da consulta da variável a seguir.

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

Passou pelo regex a seguir.

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

A lista suspensa a seguir é produzida.

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

Observação: somente nomes de grupos de captura de text e value são compatíveis.

Painéis ou linhas repetidos

Você pode criar dashboards dinâmicos usando variáveis de modelo. Todas as variáveis em suas consultas se expandem para o valor atual da variável antes que a consulta seja enviada ao banco de dados. Com variáveis, você pode reutilizar um único dashboard para todos os serviços.

Variáveis de modelo podem ser muito úteis para alterar dinamicamente suas consultas em um dashboard inteiro. Se você quiser que o Grafana crie dinamicamente novos painéis ou linhas com base nos valores que você selecionou, você pode usar o recurso Repetir.

Painéis repetidos

Caso tenha uma variável com as opções Multi-value ou Include all value ativadas, você poderá escolher um painel e fazer com que o Grafana repita esse painel para cada valor selecionado. Você pode encontrar o recurso Repetir na guia Geral no modo de edição do painel.

O direction controla como os painéis são organizados.

Se você escolher horizontal, os painéis serão organizados lado a lado. O Grafana ajusta automaticamente a largura de cada painel repetido para que toda a linha seja preenchida. Atualmente, você não pode misturar outros painéis em uma linha com um painel repetido.

Configure Max per row para informar ao Grafana quantos painéis por linha você deseja no máximo. Ele assume 4 como padrão.

Se você escolher vertical, os painéis serão organizados de cima para baixo em uma coluna. A largura dos painéis repetidos é a mesma do primeiro painel (o modelo original) que está sendo repetido.

Faça alterações somente no primeiro painel (o modelo original). Para que as alterações sejam efetivas em todos os painéis, você precisa iniciar uma reconstrução dinâmica do dashboard. Você pode fazer isso alterando o valor da variável (ou seja, a base para a repetição) ou recarregando o dashboard.

Linhas repetidas

Conforme visto acima com os painéis, você também poderá repetir as linhas se tiver variáveis definidas com uma opção de seleção Multi-value ou Include all value.

Para ativar esse recurso, você deve primeiro adicionar uma nova Linha usando o menu Adicionar painel. Em seguida, pause no título da linha e escolha o botão de engrenagem para acessar o painel de configuração Row Options. Em seguida, você pode selecionar a variável para a qual deseja repetir a linha.

A prática recomendada é usar também uma variável no título da linha.