Escrever consultas de expressão

Este tópico de documentação foi desenvolvido para espaços de trabalho do Grafana que oferecem suporte ao Grafana versão 9.x.

Para espaços de trabalho do Grafana que suportam a versão 8.x do Grafana, consulte. Trabalhando na versão 8 da Grafana

As expressões do lado do servidor permitem que você manipule dados retornados de consultas com operações matemáticas e outras. As expressões criam novos dados e não manipulam os dados retornados pelas fontes de dados.

Sobre expressões

As expressões do lado do servidor permitem que você manipule dados retornados de consultas com operações matemáticas e outras. As expressões criam novos dados e não manipulam os dados retornados pelas fontes de dados, exceto por uma pequena reestruturação de dados para tornar os dados uma entrada aceitável para expressões.

Usando expressões

As expressões são usadas principalmente pelo Grafana Alerting. O processamento é feito no lado do servidor, para que as expressões possam operar sem uma sessão do navegador. No entanto, as expressões também podem ser usadas com fontes de dados de back-end e visualização.

nota

As expressões não funcionam com alertas de painel legados.

As expressões têm como objetivo aumentar as fontes de dados, permitindo que consultas de diferentes fontes de dados sejam combinadas ou fornecendo operações indisponíveis em uma fonte de dados.

nota

Quando possível, você deve fazer o processamento de dados dentro da fonte de dados. Copiar dados do armazenamento para o servidor Grafana para processamento é ineficiente, portanto, as expressões são direcionadas ao processamento leve de dados.

As expressões funcionam com consultas de fontes de dados que retornam dados numéricos ou de séries temporais. Eles também operam com dados multidimensionais. Por exemplo, uma consulta que retorna várias séries, em que cada série é identificada por rótulos ou tags.

Uma expressão individual usa uma ou mais consultas ou outras expressões como entrada e adiciona dados ao resultado. Cada expressão ou consulta individual é representada por uma variável que é um identificador nomeado conhecido como RefID (por exemplo, a letra padrão A ouB).

Para referenciar a saída de uma expressão individual ou de uma consulta de fonte de dados em outra expressão, esse identificador é usado como uma variável.

Tipos de expressões

As expressões funcionam com dois tipos de dados.

• Uma coleção de séries temporais.

• Uma coleção de números, em que cada número é um item.

Cada coleção é retornada de uma única consulta ou expressão de fonte de dados e representada pelo RefID. Cada coleção é um conjunto, onde cada item do conjunto é identificado exclusivamente por suas dimensões, que são armazenadas como rótulos ou pares de valores-chave.

Consultas de fontes de dados

As expressões do lado do servidor só oferecem suporte a consultas de fontes de dados para fontes de dados de back-end. Geralmente, presume-se que os dados sejam rotulados como dados de séries temporais. No futuro, pretendemos adicionar uma afirmação dos dados do tipo de retorno da consulta (número ou série temporal) para que as expressões possam lidar melhor com os erros.

As consultas à fonte de dados, quando usadas com expressões, são executadas pelo mecanismo de expressão. Ao fazer isso, ele reestrutura os dados para serem uma série temporal ou um número por quadro de dados. Então, por exemplo, se estiver usando uma fonte de dados que retorna várias séries em um quadro na exibição de tabela, você pode notar que ela parece diferente quando executada com expressões.

Atualmente, o único formato de série não temporal (número) compatível com o uso de quadros de dados é que você tem uma resposta de tabela que retorna um quadro de dados sem hora, colunas de sequência de caracteres e uma coluna numérica:

Loc	Host	AVG_CPU
MIA	A	1
NYC	B	2

O exemplo acima produzirá um número que funciona com expressões. As colunas de string se tornam rótulos e a coluna numérica o valor correspondente. Por exemplo, {"Loc": "MIA", "Host": "A"} com um valor de 1.

Operações

Você pode usar as seguintes operações em expressões: matemática, redução e reamostragem.

Math (Matemática)

Math é para fórmulas matemáticas de formato livre em séries temporais ou dados numéricos. As operações matemáticas usam números e séries temporais como entrada e os alteram para números e séries temporais diferentes.

Os dados de outras consultas ou expressões são referenciados com o RefID prefixado com um cifrão, por exemplo. $A Se a variável tiver espaços no nome, você poderá usar uma sintaxe entre chaves, como. ${my variable}

As constantes numéricas podem estar em decimal (2.24), octal (com um zero à esquerda como072) ou hexadecimal (com um 0x à esquerda). 0x2A Exponenciais e sinais também são suportados (por exemplo,-0.8e-2).

Operadores

Os operadores aritméticos (+, binários e unários-,,, * /%, expoente**), relacionais (,<,,, > ==!=, >=<=) e lógicos (&&,, e unários) são || suportados. !

A forma como a operação se comporta com os dados depende se são dados numéricos ou de séries temporais.

Com operações binárias, como $A + $B ou$A || $B, o operador é aplicado das seguintes maneiras, dependendo do tipo de dados:

• Se ambos $A e $B forem um número, a operação será executada entre os dois números.

• Se uma variável for um número e a outra variável for uma série temporal, a operação entre o valor de cada ponto na série temporal e o número será executada.

• Se ambos $A $B forem dados de séries temporais, a operação entre cada valor nas duas séries será executada para cada registro de data $A e hora existente em ambas e. $B A Resample operação pode ser usada para alinhar registros de data e hora.

Resumo:

• Número número OP = número

• Número: série OP = série

• Série OP = série

Como as expressões funcionam com várias séries ou números representados por uma única variável, as operações binárias também realizam uma união (junção) entre as duas variáveis. Isso é feito com base nas etiquetas de identificação associadas a cada série ou número individual.

Portanto, se você tiver números com rótulos como {host=web01} em $A e outro número $B com os mesmos rótulos, a operação será executada entre esses dois itens em cada variável e o resultado compartilhará os mesmos rótulos. As regras para o comportamento dessa união são as seguintes:

• Um item sem rótulos se juntará a qualquer coisa.

• Se ambos $A e $B cada um contiverem apenas um item (uma série ou um número), eles se unirão.

• Se os rótulos forem matemáticos exatos, eles se juntarão.

• Se os rótulos forem um subconjunto dos outros, por exemplo, um item em $A for rotulado {host=A,dc=MIA} e um item em $B for rotulado, {host=A} eles serão unidos.

• Se dentro de uma variável, como por exemplo, $A houver chaves de tag diferentes para cada item, o comportamento da junção será indefinido.

Os operadores lógicos e relacionais retornam 0 para falso 1 para verdadeiro.

Funções matemáticas

Embora a maioria das funções exista nas próprias operações de expressão, a operação matemática tem algumas funções semelhantes aos operadores ou símbolos matemáticos. Quando as funções podem receber números ou séries, o mesmo tipo do argumento será retornado. Quando é uma série, a operação é executada para o valor de cada ponto na série.

abdômen

abs retorna o valor absoluto de seu argumento, que pode ser um número ou uma série. Por exemplo, abs(-1) ou abs($A).

is_inf

is_inf pega um número ou uma série e retorna 1 para Inf valores (negativos ou positivos) e 0 para outros valores. Por exemplo, is_inf($A).

nota

Se você precisar verificar especificamente o infinito negativo, por exemplo, você pode fazer uma comparação como$A == infn().

é_nan

is_nan pega um número ou uma série e retorna 1 para NaN valores e 0 para outros valores. Por exemplo, is_nan($A). Essa função existe porque não NaN é igual NaN a.

é_nulo

is_null pega um número ou uma série e retorna 1 para null valores e 0 para outros valores. Por exemplo, is_null($A).

é_número

is_number pega um número ou uma série e retorna 1 para todos os valores de números reais e 0 para outros valores (que sãonull, Inf+Inf-, eNaN). Por exemplo, is_number($A).

tronco

Log retorna o logaritmo natural de seu argumento, que pode ser um número ou uma série. Se o valor for menor que 0, NaN será retornado. Por exemplo, log(-1) ou log($A).

inf, infn, nan e null

Todas as funções inf, infn, nan e null retornam um único valor do nome. Eles existem principalmente para testes. Exemplo: null().

round

Round retorna um valor inteiro arredondado. Por exemplo, o round(3.123) ou o round($A).

ceil

Ceil arredonda o número até o valor inteiro mais próximo. Por exemplo, ceil(3.123) retorna 4.

floor

Floor arredonda o número para baixo até o valor inteiro mais próximo. Por exemplo,floor(3.123) retorna3.

Reduzir

Reduce usa uma ou mais séries temporais retornadas de uma consulta ou expressão e transforma cada série em um único número. Os rótulos da série temporal são mantidos como rótulos em cada número reduzido gerado.

Campos:

• Função — A função de redução a ser usada

• Entrada — A variável (RefID (comoA)) a ser reamostrada

• Modo — Permite o comportamento de controle da função de redução quando uma série contém valores não numéricos (null, NaN, +-Inf)

Funções de redução

Contagem

A contagem retorna o número de pontos em cada série.

Média

A média retorna o total de todos os valores em cada série dividido pelo número de pontos nessa série. No strict modo, se algum valor na série for nulo ou nan, ou se a série estiver vazia, NaN será retornado.

Min e Max

Min e Max retornam o menor ou maior valor da série, respectivamente. No strict modo, se algum valor na série for nulo ou nan, ou se a série estiver vazia, NaN será retornado.

Soma

A soma retorna o total de todos os valores na série. Se a série tiver comprimento zero, a soma será 0. No strict modo, se houver algum valor NaN ou Null na série, NaN será retornado.

Último

Last retorna o último número da série. Se a série não tiver valores, retorna NaN.

Modos de redução

Estrito

No modo estrito, a série de entrada é processada como está. Se algum valor na série não for numérico (null, NaN ou +-Inf), NaN será retornado.

Eliminar dados não numéricos

Nesse modo, todos os valores não numéricos (null, NaN ou +-Inf) na série de entrada são filtrados antes de executar a função de redução.

Substituir não numérico

Nesse modo, todos os valores não numéricos são substituídos por um valor predefinido.

Reamostrar

A reamostragem altera os registros de data e hora em cada série temporal para ter um intervalo de tempo consistente. O principal caso de uso é que você possa reamostrar séries temporais que não compartilham os mesmos registros de data e hora para que a matemática possa ser executada entre elas. Isso pode ser feito reamostrando cada uma das duas séries e, em seguida, em uma operação matemática referenciando as variáveis reamostradas.

Campos:

• Entrada — A variável de dados da série temporal (RefID (comoA)) a ser reamostrada

• Reamostragem para — A duração do tempo para reamostrar, por exemplo, 10s. m unidades pode ser de s segundos, h minutos, d horas, dias, w semanas e y anos.

• Diminuir a amostra — A função de redução a ser usada quando há mais de um ponto de dados por amostra de janela. Consulte a operação de redução para obter detalhes sobre o comportamento.

• Upsample — O método a ser usado para preencher uma amostra de janela que não tem pontos de dados.

  • o bloco é preenchido com o último valor conhecido

  • preenchimento com o próximo valor conhecido

  • preencha para preencher as janelas de amostra vazias com NaNs

Escreva uma expressão

Se sua fonte de dados os suportar, o Grafana exibirá o botão Expressão e mostrará todas as expressões existentes na lista do editor de consultas.

Para escrever uma expressão

1. Abra o painel.

2. Abaixo da consulta, escolha Expressão.

3. No campo Operação, selecione o tipo de expressão que você deseja escrever.

4. Escreva a expressão.

5. Escolha Aplicar.

Casos especiais

Quando qualquer fonte de dados consultada não retorna séries ou números, o mecanismo de expressão retornaNoData. Por exemplo, se uma solicitação contiver duas consultas de fonte de dados mescladas por uma expressão, se NoData for retornada por pelo menos uma das consultas de fonte de dados, o resultado retornado para toda a consulta será. NoData Para obter mais informações sobre como o Grafana Alerting processa os NoData resultados, consulte. Sem lidar com dados ou casos de erro