Fonctions foreach

Vue d’ensemble

Les fonctions foreach sont utilisées dans les calculs agrégés pour renvoyer une valeur agrégée pour chaque élément sélectionné par le filtre d’élément utilisé. Un tableau de valeurs est renvoyé.

Par exemple, la fonction avg_foreach renverra un tableau de valeurs, où chaque valeur correspond à la valeur d’historique moyenne de l’élément sélectionné, pendant l’intervalle de temps spécifié.

Le filtre d’élément fait partie de la syntaxe utilisée par les fonctions foreach. L’utilisation de caractères génériques est prise en charge dans le filtre d’élément, ce qui permet de sélectionner les éléments requis de manière très flexible.

Fonctions prises en charge

Syntaxe de fonction

Les fonctions foreach prennent en charge deux paramètres communs : item filter (voir les détails ci-dessous) et time period :

foreach_function(item filter,time period)

Par exemple :

avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)

renverra la moyenne sur cinq minutes de chaque élément « mysql.qps » dans le groupe de serveurs MySQL.

Notez que certaines fonctions prennent en charge des parameters supplémentaires.

Syntaxe du filtre d’élément

Le filtre d’élément :

/host/key[parameters]?[conditions]

se compose de quatre parties, où :

• host - nom d’hôte
• key - clé d’élément (sans paramètres)
• parameters - paramètres de la clé d’élément
• conditions - conditions basées sur le groupe d’hôtes et/ou les tags d’élément (sous forme d’expression)

Les espaces sont autorisés uniquement à l’intérieur de l’expression de conditions.

Utilisation des caractères génériques

• Un caractère générique peut être utilisé pour remplacer le nom d’hôte, la clé d’élément ou un paramètre individuel de la clé d’élément.
• Soit l’hôte, soit la clé d’élément doit être spécifié sans caractère générique. Ainsi, /host/* et /*/key sont des filtres valides, mais /*/* est invalide.
• Un caractère générique ne peut pas être utilisé pour une partie du nom d’hôte, de la clé d’élément ou d’un paramètre de clé d’élément.
• Un caractère générique ne correspond pas à plus d’un seul paramètre de clé d’élément. Ainsi, un caractère générique doit être spécifié séparément pour chaque paramètre (c’est-à-dire key[abc,*,*]).

Expression de conditions

L’expression de conditions prend en charge :

• opérandes :
  • group - groupe d’hôtes
  • tag - tag d’élément
  • "<text>" - constante de chaîne, avec le caractère d’échappement \ pour échapper " et \
• opérateurs de comparaison de chaînes sensibles à la casse : =, <>
• opérateurs logiques : and, or, not
• regroupement avec parenthèses : ( )

La mise entre guillemets des constantes de chaîne est obligatoire. Seule la comparaison complète de chaînes sensible à la casse est prise en charge.

Exemples

Un filtre complexe peut être utilisé, en faisant référence à la clé d’élément, au groupe d’hôtes et aux tags, comme l’illustrent les exemples :

Tous les éléments référencés doivent exister et collecter des données. Seuls les éléments activés sur des hôtes activés sont inclus dans les calculs. Les éléments dans l’état non pris en charge ne sont pas inclus.

La spécification d’un groupe d’hôtes parent inclut le groupe parent et tous les groupes d’hôtes imbriqués avec leurs éléments.

Période de temps

Le deuxième paramètre permet de spécifier la période de temps pour l’agrégation. La période de temps ne peut être exprimée qu’en durée ; le nombre de valeurs (préfixé par #) n’est pas pris en charge.

Les symboles d’unité pris en charge peuvent être utilisés dans ce paramètre pour plus de commodité, par exemple, « 5m » (cinq minutes) au lieu de « 300s » (300 secondes) ou « 1d » (un jour) au lieu de « 86400 » (86400 secondes).

Pour la fonction last_foreach, la période de temps est un paramètre facultatif (pris en charge depuis Zabbix 7.0), qui peut être omis :

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

La période de temps n’est pas prise en charge avec la fonction exists_foreach.

Paramètres supplémentaires

bucket_rate_foreach

Un troisième paramètre facultatif est pris en charge par la fonction bucket_rate_foreach :

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

où <parameter number> correspond à la position de la valeur « bucket » dans la clé d’élément. Par exemple, si la valeur « bucket » dans myItem[aaa,0.2] est « 0.2 », alors sa position est 2.

La valeur par défaut de <parameter number> est « 1 ».

count_foreach

Les troisième et quatrième paramètres facultatifs sont pris en charge par la fonction count_foreach :

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

Où :

• operator est l’opérateur conditionnel pour les valeurs d’élément (doit être placé entre guillemets doubles). operators pris en charge :
  eq - égal
  ne - différent
  gt - supérieur
  ge - supérieur ou égal
  lt - inférieur
  le - inférieur ou égal
  like - correspond si contient le motif (sensible à la casse)
  bitand - ET binaire
  regexp - correspondance sensible à la casse de l’expression régulière donnée dans pattern
  iregexp - correspondance insensible à la casse de l’expression régulière donnée dans pattern
  
• pattern est le motif requis (les arguments de type chaîne doivent être placés entre guillemets doubles) ; pris en charge si operator est spécifié dans le troisième paramètre.

Remarques :

• Les paramètres facultatifs operator ou pattern ne peuvent pas être laissés vides après une virgule ; ils doivent être soit entièrement omis.
• Avec bitand comme troisième paramètre, le quatrième paramètre pattern peut être spécifié sous forme de deux nombres séparés par « / » : number_to_compare_with/mask. count_foreach() calcule le « ET binaire » entre la valeur et le mask et compare le résultat à number_to_compare_with. Si le résultat du « ET binaire » est égal à number_to_compare_with, la valeur est comptée.
  Si number_to_compare_with et mask sont égaux, seul le mask doit être spécifié (sans « / »).
• Avec regexp ou iregexp comme troisième paramètre, le quatrième paramètre pattern peut être une expression régulière ordinaire ou globale (commençant par « @ »). Dans le cas des expressions régulières globales, la sensibilité à la casse est héritée des paramètres des expressions régulières globales. Aux fins de la correspondance regexp, les valeurs flottantes seront toujours représentées avec 4 chiffres décimaux après le « . ». Notez également que, pour les grands nombres, la différence entre la représentation décimale (stockée dans la base de données) et binaire (utilisée par le serveur Zabbix) peut affecter le 4e chiffre décimal.

Voir calculs agrégés pour plus de détails et d’exemples sur l’utilisation des fonctions foreach.

Comportement en fonction de la disponibilité

Le tableau suivant illustre le comportement de chaque fonction en cas de disponibilité limitée de l'hôte/de l'élément et des données d'historique.

Si l'élément est ignoré, rien n'est ajouté à l'agrégation.