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

Sintaxe da função

As funções foreach suportam dois parâmetros comuns: filtro de item (veja detalhes abaixo) e período de tempo:

foreach_function(filtro de item,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:

/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 curingas

• 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 deve ser especificado sem curinga. Portanto, /host/* e /*/key sã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 a comparação de string completa sensível a maiúsculas e minúsculas é suportada.

Exemplos

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

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.

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 conveniência, 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:

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 valores de item (deve ser colocado entre aspas duplas). operators suportados:
  eq - igual
  ne - diferente
  gt - maior
  ge - maior ou igual
  lt - menor
  le - menor ou igual
  like - corresponde se contiver o padrão (case-sensitive)
  bitand - AND bit a bit
  regexp - correspondência case-sensitive da expressão regular fornecida em pattern
  iregexp - correspondência case-insensitive da expressão regular fornecida em pattern
  
• pattern é o padrão necessário (argumentos de string devem ser colocados 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, apenas 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 diferenciação entre maiúsculas e minúsculas é herdada das configurações da expressão regular global. 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 de host/item e dados de histórico.

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