[comment]: # ({731aa9c5-510ac9cc})
# 3 Expressão de trigger

[comment]: # ({/731aa9c5-510ac9cc})

[comment]: # ({3a919b3c-473bcd5e})
#### Visão geral

Esta página descreve a sintaxe da expressão do trigger e detalhes de avaliação.

A sintaxe de uma expressão simples é:

**`function`**(`/host/item`,`time_period`)<**`operator`**><**`constant`**>

Nesta expressão, o primeiro operando (à esquerda do operador) é uma [função](#functions) com seus [parâmetros](#function-parameters) entre parênteses (normalmente o item de dados e o período de tempo).

A função é usada para analisar os dados recebidos durante o período de tempo definido, resultando em um valor calculado.

Este valor é então comparado ao segundo operando, usando o [operador](#operators). 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
```

Este trigger dispara se o número de bytes recebidos em `eth0` durante os últimos cinco minutos foi sempre superior a 100 kilobytes. Neste 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 triggers](/manual/config/triggers/trigger_examples)
-   [Detecção de problemas com triggers](/manual/config/triggers) (introdução geral)

[comment]: # ({/3a919b3c-473bcd5e})

[comment]: # ({856cad55-d4e5ef03})
#### Funções

As funções permitem analisar valores coletados, por exemplo, calcular a média ou encontrar uma string específica.

Clique no respectivo grupo de funções para ver mais detalhes.

|Grupo de funções|<|Funções|
|-|----------|----------------------------------------|
|[Funções de agregação](/manual/config/triggers/expression/aggregate/)|<|avg, bucket\_percentile, count, histogram\_quantile, item\_count, kurtosis, mad, max, min, skewness, stddevpop, stddevsamp, sum, sumofsquares, varpop, varsamp|
| |[Funções foreach](/manual/config/triggers/expression/aggregate/foreach)|avg\_foreach, bucket\_rate\_foreach, count\_foreach, exists\_foreach, last\_foreach, max\_foreach, min\_foreach, sum\_foreach|
|[Funções bit a bit](/manual/config/triggers/expression/bitwise)|<|bitand, bitlshift, bitnot, bitor, bitrshift, bitxor|
|[Funções de data e hora](/manual/config/triggers/expression/time)|<|date, dayofmonth, dayofweek, now, time|
|[Funções de histórico](/manual/config/triggers/expression/history)|<|change, changecount, count, countunique, find, first, firstclock, fuzzytime, last, lastclock, logeventid, logseverity, logsource, logtimestamp, monodec, monoinc, nodata, percentile, rate|
|[Funções de tendência](/manual/config/triggers/expression/trends)|<|baselinedev, baselinewma, trendavg, trendcount, trendmax, trendmin, trendstl, trendsum|
|[Funções matemáticas](/manual/config/triggers/expression/math)|<|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 operador](/manual/config/triggers/expression/operator)|<|between, in|
|[Funções preditivas](/manual/config/triggers/expression/predictive)|<|forecast, timeleft|
|[Funções de string](/manual/config/triggers/expression/string)|<|ascii, bitlength, bytelength, char, concat, insert, jsonpath, left, length, ltrim, mid, repeat, replace, right, rtrim, trim, xmlxpath|

Exceto quando indicado de outra forma, estas funções são suportadas em:

-   [Expressões de trigger](/manual/config/triggers/expression)
-   [Itens calculados](/manual/config/items/itemtypes/calculated)
-   [Macros de expressão](/manual/config/macros/expression_macros)

As funções foreach são suportadas apenas para [cálculos de agregação](/manual/config/items/itemtypes/calculated/aggregate).

Normalmente, as funções retornam valores numéricos para comparação.
Ao retornar strings, a comparação é possível com os operadores **=** e **<>** (veja o exemplo [Detect non-matching software on different hosts](/manual/config/triggers/trigger_examples#detect-non-matching-software-on-different-hosts)).

[comment]: # ({/856cad55-d4e5ef03})

[comment]: # ({f1c0b59d-b255de16})
#### Parâmetros da função

Os parâmetros da função permitem especificar:

-   chave do item (como `/host/key`) para funções que referenciam o histórico de um item do host
-   período de tempo (e outros parâmetros específicos da função)
-   [outras expressões](#other-expressions)

[comment]: # ({/f1c0b59d-b255de16})

[comment]: # ({c59d025d-7ea76dfe})
##### Chave do item

O item referenciado deve estar em um estado suportado (exceto para a função **nodata()**, que também é calculada para itens não suportados).

A omissão do nome do host no primeiro parâmetro (ou seja, como em `function(//key,parameter,...)`) só é suportada em determinados contextos:

-   Na fórmula de itens calculados
-   Em macros de expressão, que podem ser usadas em:
    -   O campo [*Nome do evento*](/manual/config/triggers/trigger#configuration)
    -   Nome do gráfico
    -   O rótulo dos elementos de mapa "Host" e "Trigger" [elementos de mapa](/manual/config/visualization/maps/map#adding-elements)

Nesses contextos, você também pode usar a macro [`{HOST.HOST}`](/manual/appendix/macros/supported_by_location#hosthost).
`{HOST.HOST<1-9>}` pode ser usado no caso do campo *Nome do evento* e do elemento de mapa "Trigger" para se referir 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 suportados, omitir o nome do host em expressões de trigger resultará em erro.
Veja o exemplo [Comparar cargas de CPU de longo prazo](/manual/config/triggers/trigger_examples#compare-long-term-cpu-loads) para uma ilustração do uso de barra dupla em macros de nome de evento.

[comment]: # ({/c59d025d-7ea76dfe})

[comment]: # ({85352379-cf9e09bb})
##### Período de tempo

Parâmetros específicos da função são colocados após a chave do item e são separados da chave do item por uma vírgula.

A maioria das funções numéricas aceita **período de tempo** como parâmetro.
Ele permite especificar o intervalo de interesse.
Ele pode ser especificado como 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](/manual/appendix/suffixes) para indicar o período de tempo.
Precedido por um caractere de hash, o parâmetro tem um significado diferente:

|Expression|Description|
|----------|-----------|
|**sum**(/host/key,**10m)**|Soma dos valores nos últimos 10 minutos.|
|**sum**(/host/key,**\#10)**|Soma dos últimos dez valores.|

Parâmetros com um caractere de hash têm um significado diferente com a função **last** - eles denotam o N-ésimo valor anterior, então, dados os valores 30, 70, 20, 60, 50 (do mais recente para o menos recente):

-   `last(/host/key,#2)` retornaria '70'
-   `last(/host/key,#5)` retornaria '50'

O período de tempo é medido até "agora" - onde "agora" é o horário da última recálculo do trigger (veja [Frequência de cálculo](/manual/config/triggers#calculation-frequency)); "agora" não é o horário "agora" do server.

O período de tempo especifica:

-   Todos os valores entre "agora - período de tempo" e "agora" (ou, com deslocamento de tempo aplicado, entre "agora - deslocamento de tempo - período de tempo" e "agora - deslocamento de tempo").
-   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 item calculado que usa essa função se torna não suportado.

Observe que:

-   Se apenas uma única função (referenciando o histórico de dados) for usada no
    trigger, "agora" é sempre o valor mais recente recebido. Por exemplo, se
    o último valor foi recebido há uma hora, o período de tempo será
    considerado até o valor mais recente de uma hora atrás.
-   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
    [date and time](/manual/config/triggers/expression/time) e [nodata()](/manual/config/triggers/expression/history#nodata). Assim, o trigger será calculado mesmo
    que talvez o período de tempo definido (por exemplo, uma hora) ainda
    não tenha passado desde que o trigger foi criado. O trigger também
    será calculado após o primeiro valor, mesmo que o intervalo de
    tempo tenha sido definido, por exemplo, para os dez valores mais recentes.

[comment]: # ({/85352379-cf9e09bb})

[comment]: # ({da3613bd-6699e631})
##### Deslocamento de tempo

Um deslocamento de tempo opcional é suportado com tempo ou contagem de valores como parâmetro da função.
Este parâmetro permite referenciar dados de um período de tempo no passado.

O deslocamento de tempo começa com `now` - especificando o tempo atual, e é seguido por `+N<unidade de tempo>` ou `-N<unidade de tempo>` - para adicionar ou subtrair N unidades de tempo.

Por exemplo, `avg(/host/key,1h:now-1d)` retornará o valor médio para uma hora de um dia atrás.

::: noteimportant
O deslocamento de tempo especificado em meses (M) e anos (y) é suportado apenas para [funções de tendência](/manual/config/triggers/expression/trends). Outras funções suportam segundos (s), minutos (m), horas (h), dias (d) e semanas (w).
:::

**Deslocamento de tempo com períodos de tempo absolutos**

Períodos de tempo absolutos são suportados no parâmetro de deslocamento de tempo, por exemplo, meia-noite até meia-noite para um dia, segunda-feira a domingo para uma semana, primeiro dia ao último dia do mês para um mês.

O deslocamento de tempo para períodos de tempo absolutos começa com `now` - especificando o tempo atual, e é seguido por qualquer número de operações de tempo: `/<unidade de tempo>` - define o início e o fim da unidade de tempo, por exemplo, meia-noite até meia-noite para um dia, `+N<unidade de tempo>` ou `-N<unidade de tempo>` - 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.

|Parâmetro|Descrição|
|--|--------|
|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|

[comment]: # ({/da3613bd-6699e631})

[comment]: # ({7fc33108-c5d3ec54})
##### Outras expressões

Os parâmetros da função podem conter outras expressões, conforme a seguinte sintaxe:

```default
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](/manual/config/items/itemtypes/calculated).

[comment]: # ({/7fc33108-c5d3ec54})

[comment]: # ({2ef1f03c-10bc91a2})
#### 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](/manual/config/triggers/expression#unknown-expression-state)**|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<br>(sim, Desconhecido, não 0 - para não perder<br>Desconhecido em operações aritméticas)<br>1.2 **\*** Desconhecido → Desconhecido|Sim|
|<|**/**|Divisão|Desconhecido **/** 0 → erro<br>Desconhecido **/** 1.2 → Desconhecido<br>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:<br><br>A<B ⇔ (A<B-0.000001)|1.2 **<** Desconhecido → Desconhecido|Sim|
|<|**<=**|Menor ou igual a. O operador é definido como:<br><br>A<=B ⇔ (A≤B+0.000001)|Desconhecido **<=** Desconhecido → Desconhecido|Sim|
|<|**>**|Maior que. O operador é definido como:<br><br>A>B ⇔ (A>B+0.000001)| |Sim|
|<|**>=**|Maior ou igual a. O operador é definido como:<br><br>A>=B ⇔ (A≥B-0.000001)| |Sim|
|**6**|**=**|Igual a. O operador é definido como:<br><br>A=B ⇔ (A≥B-0.000001) e (A≤B+0.000001)| |Não ^**1**^|
|<|**<>**|Diferente de. O operador é definido como:<br><br>A<>B ⇔ (A<B-0.000001) ou (A>B+0.000001)| |Não ^**1**^|
|**7**|**and**|AND lógico|0 **and** Desconhecido → 0<br>1 **and** Desconhecido → Desconhecido<br>Desconhecido **and** Desconhecido → Desconhecido|Sim|
|**8**|**or**|OR lógico|1 **or** Desconhecido → 1<br>0 **or** Desconhecido → Desconhecido<br>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'.

[comment]: # ({/2ef1f03c-10bc91a2})

[comment]: # ({a5181770-cad1df72})
#### Estado de expressão desconhecido

É 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

Neste caso, a expressão do trigger geralmente é avaliada como `Desconhecido` (pois não pode ser avaliada)

É possível [ser notificado](/manual/config/events/sources#internal-events) sobre triggers desconhecidos.

**Exceções**

Apesar de um operando desconhecido, as expressões de trigger podem ser avaliadas para um resultado conhecido (Problema/OK) em alguns casos:

-   A função [`nodata()`](/manual/config/triggers/trigger/expression/history#nodata) é avaliada independentemente de o item referenciado ser suportado ou não.
-   Expressões com AND/OR podem ser avaliadas para um resultado conhecido em dois casos:
    -   **Caso 1**: "`1 or some_function(unsupported_item1) or some_function(unsupported_item2) or ...`" é avaliado para um resultado conhecido ('1' ou "Problema"),
    -   **Caso 2**: "`0 and some_function(unsupported_item1) and some_function(unsupported_item2) and ...`" é avaliado para um resultado conhecido ('0' ou "OK").
-   Se a avaliação da função para um item suportado resultar em erro, o valor da função se torna `Desconhecido` e ela participa como operando desconhecido em avaliações posteriores da expressão.

Operandos desconhecidos podem "desaparecer" apenas em expressões lógicas, conforme descrito acima.
Em expressões aritméticas, operandos desconhecidos sempre levam a `Desconhecido` (exceto divisão por 0).

::: noteimportant
O estado de expressão desconhecido não altera o estado do trigger (Problema/OK).
Portanto, se o estado do trigger era "Problema" (veja o Caso 1), ele permanece no estado de problema mesmo que a parte conhecida seja resolvida ('1' se torne '0'), porque a expressão agora é avaliada como `Desconhecido` 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 `Desconhecido`, a mensagem de erro no frontend se refere ao último item não suportado avaliado.

[comment]: # ({/a5181770-cad1df72})

[comment]: # ({0e2466bf-195c3f4f})
#### 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.

::: noteclassic
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.
:::

[comment]: # ({/0e2466bf-195c3f4f})