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 selecionado pelo filtro de item usado. É retornado um array de valores.

Por exemplo, a função avg_foreach retornará um array de valores, em que cada valor é o valor de histórico médio 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, portanto os itens necessários podem ser selecionados de forma bastante flexível.

Funções suportadas

Sintaxe da função

As funções Foreach suportam dois parâmetros comuns: item filter (veja os detalhes abaixo) e time period:

foreach_function(item filter,time period)

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:

/host/key[parameters]?[conditions]

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 wildcard

• O wildcard 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 deve ser especificado sem wildcard. Assim, /host/* e /*/key são filtros válidos, mas /*/* é inválido.
• O wildcard não pode ser usado para uma parte do nome do host, da chave do item ou do parâmetro da chave do item.
• O wildcard não corresponde a mais de um único parâmetro da chave do item. Assim, um wildcard 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 completa de string sensível a maiúsculas e minúsculas é suportada.

Exemplos

Um filtro complexo pode ser usado, referenciando a chave do item, o grupo de host e as tags, como ilustrado pelos exemplos:

Todos os itens referenciados devem existir e coletar dados. Somente itens habilitados em hosts habilitados são incluídos nos cálculos. Itens no estado não suportado não são incluídos.

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 parâmetro segundo 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.

Símbolos de unidade suportados podem ser usados neste parâmetro por conveniência, por exemplo, 5m (cinco minutos) em vez de 300s (300 segundos) ou 1d (um dia) em vez 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:

last_foreach(/*/key?[group="host group"])

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:

bucket_rate_foreach(item filter,time period,<parameter number>)

onde <parameter number> é 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 <parameter number> é 1.

count_foreach

Terceiro e quarto parâmetros opcionais são suportados pela função count_foreach:

count_foreach(item filter,time period,<operator>,<pattern>)

Onde:

• operator é o operador condicional para os valores do item (deve estar entre aspas duplas). Operadores suportados:
  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 com diferenciação de maiúsculas e minúsculas da expressão regular fornecida em pattern
  iregexp - correspondência sem diferenciação de maiúsculas e minúsculas da expressão regular fornecida em pattern.
  
• pattern é o padrão obrigatório (argumentos de string devem estar entre aspas duplas); suportado se operator for especificado no terceiro parâmetro.

Comentários:

• Os parâmetros opcionais operator ou pattern não podem ser deixados em branco após uma vírgula; devem ser totalmente omitidos.
• Com bitand como terceiro parâmetro, o quarto parâmetro pattern pode ser especificado como dois números, separados por '/': number_to_compare_with/mask. count_foreach() calcula o "AND bit a bit" do valor e da mask e compara o resultado com number_to_compare_with. Se o resultado do "AND bit a bit" for igual a number_to_compare_with, o valor é contado.
  Se number_to_compare_with e mask forem iguais, apenas a mask precisa ser especificada (sem '/').
• Com regexp ou iregexp como terceiro parâmetro, o quarto parâmetro pattern pode ser uma expressão regular comum ou global (começando com '@'). No caso de expressões regulares globais, a sensibilidade a maiúsculas e minúsculas é herdada das configurações da expressão regular global. Para fins de correspondência de regexp, valores de ponto flutuante sempre serão representados com 4 dígitos decimais após '.'. Observe também que, para números grandes, a diferença entre a representação decimal (armazenada no banco de dados) e binária (usada pelo Zabbix server) pode afetar o 4º dígito decimal.

Consulte cálculos agregados para mais detalhes e exemplos de 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 de host/item e dados de histórico.

Se o item for ignorado, nada é adicionado à agregação.