Table of Contents
1 Funções Foreach
Visão geral
As funções Foreach são usadas em cálculos agregados para retornar um valor agregado para cada item que é selecionado pelo filtro de item utilizado. Um array de valores é retornado.
Por exemplo, a função avg_foreach retornará um array de valores, onde cada valor é o valor médio do histórico do item selecionado, durante o intervalo de tempo especificado.
O filtro de item faz parte da sintaxe usada pelas funções foreach. O uso de curingas é suportado no filtro de item, permitindo que os itens necessários sejam selecionados de forma bastante flexível.
Funções suportadas
| Função | Descrição |
|---|---|
| avg_foreach | Retorna o valor médio para cada item. |
| bucket_rate_foreach | Retorna pares (limite superior do bucket, valor da taxa) adequados para uso na função histogram_quantile(), onde "limite superior do bucket" é o valor do parâmetro da chave do item definido pelo <número do parâmetro> parâmetro. |
| count_foreach | Retorna o número de valores para cada item. |
| exists_foreach | Retorna '1' para cada item habilitado. |
| last_foreach | Retorna o último valor para cada item. |
| max_foreach | Retorna o valor máximo para cada item. |
| min_foreach | Retorna o valor mínimo para cada item. |
| sum_foreach | Retorna a soma dos valores para cada item. |
Sintaxe da função
As funções foreach suportam dois parâmetros comuns: filtro de item (veja detalhes abaixo) e período de tempo:
Por exemplo:
avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)
retornará a média de cinco minutos de cada item 'mysql.qps' no grupo de servidores MySQL.
Observe que algumas funções suportam parâmetros adicionais.
Sintaxe do filtro de item
O filtro de item:
consiste em quatro partes, onde:
- host - nome do host
- key - chave do item (sem parâmetros)
- parameters - parâmetros da chave do item
- conditions - condições baseadas em grupo de host e/ou tag de item (como expressão)
Espaços são permitidos apenas dentro da expressão de condições.
Uso de curinga
- O curinga pode ser usado para substituir o nome do host, a chave do item ou um parâmetro individual da chave do item.
- Ou o host ou a chave do item devem ser especificados sem curinga. Portanto,
/host/*e/*/keysão filtros válidos, mas/*/*é inválido. - O curinga não pode ser usado para parte do nome do host, chave do item ou parâmetro da chave do item.
- O curinga não corresponde a mais de um parâmetro da chave do item. Portanto, um curinga deve ser especificado para cada parâmetro separadamente (ou seja,
key[abc,*,*]).
Expressão de condições
A expressão de condições suporta:
- operandos:
- group - grupo de host
- tag - tag de item
"<text>"- constante de string, com o caractere de escape\para escapar"e\
- operadores de comparação de string sensíveis a maiúsculas e minúsculas:
=,<> - operadores lógicos:
and,or,not - agrupamento com parênteses:
()
A citação de constantes de string é obrigatória. Apenas comparação de string completa e sensível a maiúsculas e minúsculas é suportada.
Ao especificar tags no filtro (ou seja, tag="tagname:value"), o dois-pontos ":" é usado como delimitador. Tudo após ele é considerado o valor da tag. Portanto, atualmente não é suportado especificar um nome de tag contendo ":" nele.
Exemplos
Um filtro complexo pode ser usado, referenciando a chave do item, grupo de host e tags, conforme ilustrado pelos exemplos:
| Exemplo de sintaxe | Descrição |
|---|---|
/host/key[abc,*] |
Corresponde a itens semelhantes neste host. |
/*/key |
Corresponde ao mesmo item de qualquer host. |
/*/key?[group="ABC" and tag="tagname:value"] |
Corresponde ao mesmo item de qualquer host do grupo ABC que tenha tags 'tagname:value'. |
/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))] |
Corresponde a itens semelhantes de qualquer host do grupo ABC ou DEF com as respectivas tags. |
Todos os itens referenciados devem existir e coletar dados. Apenas itens habilitados em hosts habilitados são incluídos nos cálculos. Itens em estado não suportado não são incluídos.
Se a chave do item de um item referenciado for alterada, o filtro deverá ser atualizado manualmente.
Especificar um grupo de host pai inclui o grupo pai e todos os grupos de host aninhados com seus itens.
Período de tempo
O segundo parâmetro permite especificar o período de tempo para agregação. O período de tempo só pode ser expresso como tempo, a quantidade de valores (prefixada com #) não é suportada.
Unidades de tempo suportadas podem ser usadas neste parâmetro para maior comodidade, por exemplo, '5m' (cinco minutos) ao invés de '300s' (300 segundos) ou '1d' (um dia) ao invés de '86400' (86400 segundos).
Para a função last_foreach, o período de tempo é um parâmetro opcional (suportado desde o Zabbix 7.0), que pode ser omitido:
O período de tempo não é suportado com a função exists_foreach.
Parâmetros adicionais
bucket_rate_foreach
Um terceiro parâmetro opcional é suportado pela função bucket_rate_foreach:
onde <número do parâmetro> é a posição do valor "bucket" na chave do item. Por exemplo, se o valor "bucket" em myItem[aaa,0.2] for '0.2', então sua posição é 2.
O valor padrão de <número do parâmetro> é '1'.
count_foreach
Terceiro e quarto parâmetros opcionais são suportados pela função count_foreach:
Onde:
- operador é o operador condicional para valores de item (deve ser colocado entre aspas duplas).
operadoressuportados:
eq - igual
ne - diferente
gt - maior
ge - maior ou igual
lt - menor
le - menor ou igual
like - corresponde se contiver o padrão (diferencia maiúsculas de minúsculas)
bitand - AND bit a bit
regexp - correspondência sensível a maiúsculas/minúsculas da expressão regular fornecida empadrão
iregexp - correspondência insensível a maiúsculas/minúsculas da expressão regular fornecida empadrão - padrão é o padrão necessário (argumentos de string devem estar entre aspas duplas); suportado se operador for especificado no terceiro parâmetro.
Comentários:
- Os parâmetros opcionais operador ou padrão não podem ser deixados em branco após uma vírgula, apenas totalmente omitidos.
- Com bitand como terceiro parâmetro, o quarto parâmetro
padrãopode ser especificado como dois números, separados por '/': numero_para_comparar/mascara. count_foreach() calcula o "AND bit a bit" do valor e da máscara e compara o resultado com numero_para_comparar. Se o resultado do "AND bit a bit" for igual a numero_para_comparar, o valor é contado.
Se numero_para_comparar e máscara forem iguais, apenas a máscara precisa ser especificada (sem '/'). - Com regexp ou iregexp como terceiro parâmetro, o quarto parâmetro
padrãopode ser uma expressão regular comum ou global (começando com '@'). No caso de expressões regulares globais, a diferenciação de maiúsculas/minúsculas é herdada das configurações globais de expressão regular. Para fins de correspondência regexp, valores float sempre serão representados com 4 dígitos decimais após o '.'. Observe também que, para números grandes, a diferença na representação decimal (armazenada no banco de dados) e binária (usada pelo Zabbix server) pode afetar o 4º dígito decimal.
Veja cálculos agregados para mais detalhes e exemplos sobre o uso das funções foreach.
Comportamento dependendo da disponibilidade
A tabela a seguir ilustra como cada função se comporta em casos de disponibilidade limitada do host/item e dos dados de histórico.
| Função | Host desabilitado | Host indisponível com dados | Host indisponível sem dados | Item desabilitado | Item não suportado | Erro de recuperação de dados (SQL) |
|---|---|---|---|---|---|---|
| avg_foreach | ignorar | retornar média | ignorar | ignorar | ignorar | ignorar |
| bucket_rate_foreach | ignorar | retornar bucket rate | ignorar | ignorar | ignorar | ignorar |
| count_foreach | ignorar | retornar contagem | 0 | ignorar | ignorar | ignorar |
| exists_foreach | ignorar | 1 | 1 | ignorar | 1 | n/a |
| last_foreach | ignorar | retornar último | ignorar | ignorar | ignorar | ignorar |
| max_foreach | ignorar | retornar máximo | ignorar | ignorar | ignorar | ignorar |
| min_foreach | ignorar | retornar mínimo | ignorar | ignorar | ignorar | ignorar |
| sum_foreach | ignorar | retornar soma | ignorar | ignorar | ignorar | ignorar |
Se o item for ignorado, nada é adicionado à agregação.