Expressão de trigger e funções
Visão geral
Esta página descreve a sintaxe das expressões de trigger e os detalhes de sua avaliação.
A sintaxe de uma expressão simples é:
function(/host/item,time_period)<operator><constant>
Nessa expressão, o primeiro operando (à esquerda do operador) é uma função com seus parâmetros entre parênteses (normalmente o item de dados e o período).
A função é usada para analisar os dados recebidos durante o período definido, resultando em um valor calculado.
Esse valor é então comparado ao segundo operando usando o operador. Neste exemplo, o segundo operando é uma constante, mas também pode ser outra função.
Por exemplo:
min(/Zabbix server/net.if.in[eth0,bytes],5m)>100K
Esse trigger é acionado se o número de bytes recebidos em eth0 durante os últimos cinco minutos tiver permanecido sempre acima de 100 kilobytes.
Nesse caso, a expressão é verdadeira e um problema é criado.
As expressões de trigger são extremamente flexíveis. Em expressões mais complexas, várias funções, operadores e constantes podem ser combinados.
Veja também:
- Exemplos de trigger
- Detecção de problemas com triggers (introdução geral)
Funções
As funções permitem analisar valores coletados, por exemplo, calcular a média ou localizar uma string específica.
Clique no grupo de funções correspondente para ver mais detalhes.
| Grupo de funções | Funções | |
|---|---|---|
| Funções de agregação | avg, bucket_percentile, count, histogram_quantile, item_count, kurtosis, mad, max, min, skewness, stddevpop, stddevsamp, sum, sumofsquares, varpop, varsamp | |
| Funções Foreach | avg_foreach, bucket_rate_foreach, count_foreach, exists_foreach, last_foreach, max_foreach, min_foreach, sum_foreach | |
| Funções bit a bit | bitand, bitlshift, bitnot, bitor, bitrshift, bitxor | |
| Funções de data e hora | date, dayofmonth, dayofweek, now, time | |
| Funções de histórico | change, changecount, count, countunique, find, first, firstclock, fuzzytime, jsonpath, last, lastclock, logeventid, logseverity, logsource, logtimestamp, monodec, monoinc, nodata, percentile, rate, xmlxpath | |
| Funções de tendências | baselinedev, baselinewma, trendavg, trendcount, trendmax, trendmin, trendstl, trendsum | |
| Funções matemáticas | abs, acos, asin, atan, atan2, avg, cbrt, ceil, cos, cosh, cot, degrees, e, exp, expm1, floor, log, log10, max, min, mod, pi, power, radians, rand, round, signum, sin, sinh, sqrt, sum, tan, truncate | |
| Funções de operadores | between, in | |
| Funções preditivas | forecast, timeleft | |
| Funções de string | ascii, bitlength, bytelength, char, concat, contains, insert, jsonpath, left, length, ltrim, mid, repeat, replace, right, rtrim, substring, trim, xmlxpath | |
Exceto quando indicado de outra forma, estas funções são compatíveis com:
As funções Foreach são compatíveis somente com cálculos de agregação.
Normalmente, as funções retornam valores numéricos para comparação. Ao retornar strings, a comparação é possível com os operadores = e <> (consulte o exemplo Detectar software não correspondente em hosts diferentes).
Parâmetros de função
Os parâmetros de função permitem especificar:
- a chave do item (como
/host/key) para funções que fazem referência ao histórico de um item do host - o período de tempo (e outros parâmetros específicos da função)
- outras expressões
Chave do item
O item referenciado deve estar em um estado compatível (exceto para a função nodata(), que também é calculada para itens sem suporte).
A omissão do nome do host no primeiro parâmetro (ou seja, como em function(//key,parameter,...)) é compatível apenas em determinados contextos:
- Na fórmula de itens calculados
- Em macros de expressão, que podem ser usadas em:
- O campo Nome do evento
- Nome do gráfico
- O rótulo dos elementos de mapa "Host" e "Trigger"
Nesses contextos, você também pode usar a macro {HOST.HOST}.
{HOST.HOST<1-9>} pode ser usada no caso do campo Nome do evento e do elemento de mapa "Trigger" para fazer referência a um item específico na expressão do trigger.
Quando o nome do host é omitido ou substituído por {HOST.HOST} nesses contextos, a referência aponta para o primeiro item na expressão do trigger ou para o primeiro item no gráfico.
Fora desses contextos compatíveis, omitir o nome do host nas expressões do trigger resultará em um erro.
Consulte o exemplo Comparar cargas de CPU de longo prazo para ver uma ilustração do uso de duas barras em macros de nome do evento.
Período de tempo
Os parâmetros específicos da função são colocados após a chave do item e separados dela por uma vírgula.
A maioria das funções numéricas aceita um período de tempo como parâmetro.
Ele permite especificar o intervalo de nosso interesse.
Ele pode ser especificado como um período de tempo (30s, 10m, 1h) ou como um intervalo de valores (#5 - para os cinco valores mais recentes).
Você pode usar segundos ou sufixos de tempo para indicar o período de tempo.
Quando precedido por um símbolo de cerquilha, o parâmetro tem um significado diferente:
| Expression | Description |
|---|---|
| sum(/host/key,10m) | Soma dos valores dos últimos 10 minutos. |
| sum(/host/key,#10) | Soma dos dez últimos valores. |
Os parâmetros com um símbolo de cerquilha têm um significado diferente com a função last - eles indicam o N-ésimo valor anterior. Portanto, considerando os valores 30, 70, 20, 60, 50 (do mais recente ao menos recente):
last(/host/key,#2)retornaria '70'last(/host/key,#5)retornaria '50'
O período de tempo é medido até "agora" - em que "agora" é o horário do recálculo mais recente do trigger (consulte Frequência de cálculo); "agora" não é o horário atual do server.
O período de tempo especifica:
- Todos os valores entre "agora - período de tempo" e "agora" (ou, com o deslocamento de tempo aplicado, entre "agora - deslocamento de tempo - período de tempo" e "agora").
- O número especificado de valores do passado, até "agora".
Se não existirem dados para o período de avaliação especificado, o trigger ou o item calculado que usa essa função ficará sem suporte.
Observe que:
- Se apenas uma única função (que referencia o histórico de dados) for usada no trigger, "agora" será sempre o valor recebido mais recentemente.
Por exemplo, se o último valor tiver sido recebido há uma hora, o período de tempo será considerado até o valor mais recente recebido há uma hora. - Um novo trigger é calculado assim que o primeiro valor é recebido (funções de histórico); ele será calculado em até 30 segundos para as funções de data e hora e nodata().
Assim, o trigger será calculado mesmo que o período de tempo definido (por exemplo, uma hora) ainda não tenha transcorrido desde a criação do trigger.
O trigger também será calculado após o primeiro valor, mesmo que o intervalo de tempo tenha sido definido, por exemplo, como os dez valores mais recentes.
Deslocamento de tempo
Um deslocamento de tempo opcional é compatível com o tempo ou a contagem de valores como parâmetro da função. Esse parâmetro permite referenciar dados de um período no passado.
O deslocamento de tempo começa com now - especificando o horário atual, e é seguido por +N<time unit> ou -N<time unit> - para adicionar ou subtrair N unidades de tempo.
Por exemplo, avg(/host/key,1h:now-1d) retornará o valor médio de uma hora de um dia atrás.
O deslocamento de tempo especificado em meses (M) e anos (y) é compatível apenas com funções de tendência. Outras funções são compatíveis com segundos (s), minutos (m), horas (h), dias (d) e semanas (w).
Deslocamento de tempo com períodos absolutos
Períodos absolutos são compatíveis com o parâmetro de deslocamento de tempo, por exemplo, da meia-noite à meia-noite para um dia, de segunda-feira a domingo para uma semana, do primeiro ao último dia do mês para um mês.
O deslocamento de tempo para períodos absolutos começa com now - especificando o horário atual, e é seguido por qualquer número de operações de tempo: /<time unit> - define o início e o fim da unidade de tempo, por exemplo, da meia-noite à meia-noite para um dia, +N<time unit> ou -N<time unit> - para adicionar ou subtrair N unidades de tempo.
Observe que o valor do deslocamento de tempo pode ser maior ou igual a 0, enquanto o valor mínimo do período de tempo é 1.
| Parameter | Description |
|---|---|
| 1d:now/d | Ontem |
| 1d:now/d+1d | Hoje |
| 2d:now/d+1d | Últimos 2 dias |
| 1w:now/w | Semana passada |
| 1w:now/w+1w | Esta semana |
Outras expressões
Os parâmetros da função podem conter outras expressões, conforme a seguinte sintaxe:
min(min(/host/key,1h),min(/host2/key2,1h)*10)
Observe que outras expressões não podem ser usadas se a função fizer referência ao histórico do item. Por exemplo, a seguinte sintaxe não é permitida:
min(/host/key,#5*10)
Enquanto outras expressões de trigger como parâmetros de função são limitadas a funções que não usam histórico em triggers, essa limitação não se aplica em itens calculados.
Operadores
Os seguintes operadores são suportados para triggers (em ordem decrescente de prioridade de execução):
| Prioridade | Operador | Definição | Notas para valores desconhecidos | Forçar conversão do operando para float 1 |
|---|---|---|---|---|
| 1 | - | Menos unário | -Desconhecido → Desconhecido | Sim |
| 2 | not | NOT lógico | not Desconhecido → Desconhecido | Sim |
| 3 | * | Multiplicação | 0 * Desconhecido → Desconhecido (sim, Desconhecido, não 0 - para não perder Desconhecido em operações aritméticas) 1.2 * Desconhecido → Desconhecido |
Sim |
| / | Divisão | Desconhecido / 0 → erro Desconhecido / 1.2 → Desconhecido 0.0 / Desconhecido → Desconhecido |
Sim | |
| 4 | + | Soma aritmética | 1.2 + Desconhecido → Desconhecido | Sim |
| - | Subtração aritmética | 1.2 - Desconhecido → Desconhecido | Sim | |
| 5 | < | Menor que. O operador é definido como: A<B ⇔ (A<B-0.000001) |
1.2 < Desconhecido → Desconhecido | Sim |
| <= | Menor ou igual a. O operador é definido como: A<=B ⇔ (A≤B+0.000001) |
Desconhecido <= Desconhecido → Desconhecido | Sim | |
| > | Maior que. O operador é definido como: A>B ⇔ (A>B+0.000001) |
Sim | ||
| >= | Maior ou igual a. O operador é definido como: A>=B ⇔ (A≥B-0.000001) |
Sim | ||
| 6 | = | Igual a. O operador é definido como: A=B ⇔ (A≥B-0.000001) e (A≤B+0.000001) |
Não 1 | |
| <> | Diferente de. O operador é definido como: A<>B ⇔ (A<B-0.000001) ou (A>B+0.000001) |
Não 1 | ||
| 7 | and | AND lógico | 0 and Desconhecido → 0 1 and Desconhecido → Desconhecido Desconhecido and Desconhecido → Desconhecido |
Sim |
| 8 | or | OR lógico | 1 or Desconhecido → 1 0 or Desconhecido → Desconhecido Desconhecido or Desconhecido → Desconhecido |
Sim |
1 O operando string ainda é convertido para numérico se:
- outro operando for numérico
- operador diferente de = ou <> for usado em um operando
(Se a conversão falhar - o operando numérico é convertido para string e ambos os operandos são comparados como strings.)
Os operadores not, and e or diferenciam maiúsculas de minúsculas e devem estar em minúsculas. Eles também devem ser cercados por espaços ou parênteses.
Todos os operadores, exceto - unário e not, têm associatividade da esquerda para a direita. - unário e not são não associativos (ou seja, -(-1) e not (not 1) devem ser usados em vez de --1 e not not 1).
Resultado da avaliação:
- Os operadores <, <=, >, >=, =, <> devem retornar '1' na expressão do trigger se a relação especificada for verdadeira e '0' se for falsa. Se pelo menos um operando for Desconhecido, o resultado será Desconhecido;
- and para operandos conhecidos deve retornar '1' se ambos os operandos forem diferentes de '0'; caso contrário, retorna '0'; para operandos desconhecidos, and retorna '0' apenas se um operando for igual a '0'; caso contrário, retorna 'Desconhecido';
- or para operandos conhecidos deve retornar '1' se qualquer um dos operandos for diferente de '0'; caso contrário, retorna '0'; para operandos desconhecidos, or retorna '1' apenas se um operando for diferente de '0'; caso contrário, retorna 'Desconhecido';
- O resultado do operador de negação lógica not para um operando conhecido é '0' se o valor do operando for diferente de '0'; '1' se o valor do operando for igual a '0'. Para operando desconhecido, not retorna 'Desconhecido'.
Estado desconhecido da expressão
É possível que um operando desconhecido apareça em uma expressão de trigger quando:
- um item não suportado é usado
- a avaliação da função, para um item suportado, resulta em erro
Nesse caso, a expressão do trigger geralmente é avaliada como Unknown (pois não pode ser avaliada).
É possível receber notificações sobre triggers desconhecidos.
Exceções
Apesar de um operando desconhecido, as expressões de trigger podem ser avaliadas como um resultado conhecido (Problem/OK) em alguns casos:
- A função
nodata()é avaliada independentemente de o item referenciado ser suportado ou não. - Expressões com AND/OR podem ser avaliadas como um resultado conhecido em dois casos:
- Caso 1: "
1 or some_function(unsupported_item1) or some_function(unsupported_item2) or ..." é avaliada como um resultado conhecido ('1' ou "Problem"), - Caso 2: "
0 and some_function(unsupported_item1) and some_function(unsupported_item2) and ..." é avaliada como um resultado conhecido ('0' ou "OK").
- Caso 1: "
- Se a avaliação da função para um item suportado resultar em erro, o valor da função se tornará
Unknowne participará como um operando desconhecido na avaliação posterior da expressão.
Os operandos desconhecidos podem "desaparecer" somente em expressões lógicas, conforme descrito acima.
Em expressões aritméticas, os operandos desconhecidos sempre resultam em Unknown (exceto na divisão por 0).
O estado desconhecido da expressão não altera o estado do trigger (Problem/OK).
Portanto, se o estado do trigger era "Problem" (consulte o Caso 1), ele permanece no estado de problema mesmo que a parte conhecida seja resolvida ('1' se torne '0'), pois a expressão agora é avaliada como Unknown, e isso não altera o estado do trigger.
Se uma expressão de trigger com vários itens não suportados for avaliada como Unknown, a mensagem de erro no frontend fará referência ao último item não suportado avaliado.
Cache de valores
Os valores necessários para a avaliação do trigger são armazenados em cache pelo Zabbix server. Por causa disso, a avaliação do trigger causa uma carga maior no banco de dados por algum tempo após a reinicialização do server. O cache de valores não é limpo quando os valores do histórico do item são removidos (seja manualmente ou pelo housekeeper), então o server usará os valores em cache até que eles sejam mais antigos do que os períodos de tempo definidos nas funções do trigger ou até que o server seja reiniciado.
Se não houver dados recentes no cache e não houver um período de consulta definido na função, o Zabbix, por padrão, irá buscar no passado até uma semana para consultar o banco de dados por valores históricos.