Fonctions foreach

Présentation générale

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éments utilisé. Un tableau de valeurs est renvoyé.

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

Les fonctions foreach sont prises en charge uniquement dans les formules des éléments calculés. Elles ne peuvent pas être invoquées dans des clés d’éléments simples ni utilisées directement pour créer des expressions de déclencheurs. Dans les expressions de déclencheurs, un élément calculé peut être utilisé en faisant référence à sa clé.

Le filtre d’éléments 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éments, ce qui permet de sélectionner les éléments requis avec une grande flexibilité.

Fonctions prises en charge

Function Description
avg_foreach Renvoie la valeur moyenne pour chaque élément.
bucket_rate_foreach Renvoie des paires (borne supérieure du bucket, valeur du taux) adaptées à l'utilisation dans la fonction histogram_quantile(), où "borne supérieure du bucket" est la valeur du paramètre de clé d'élément définie par le paramètre <parameter number>.
count_foreach Renvoie le nombre de valeurs pour chaque élément.
exists_foreach Renvoie '1' pour chaque élément activé.
last_foreach Renvoie la dernière valeur pour chaque élément.
max_foreach Renvoie la valeur maximale pour chaque élément.
min_foreach Renvoie la valeur minimale pour chaque élément.
sum_foreach Renvoie la somme des valeurs pour chaque élément.

Syntaxe des fonctions

Les fonctions foreach prennent en charge deux paramètres communs : filtre d’élément (voir les détails ci-dessous) et période de temps :

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 paramètres 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.

Lors de la spécification des tags dans le filtre (c’est-à-dire tag="tagname:value"), le deux-points ":" est utilisé comme délimiteur. Tout ce qui suit est considéré comme la valeur du tag. Ainsi, il n’est actuellement pas possible de spécifier un nom de tag contenant ":".

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 :

Exemple de syntaxe Description
/host/key[abc,*] Correspond à des éléments similaires sur cet hôte.
/*/key Correspond au même élément de n’importe quel hôte.
/*/key?[group="ABC" and tag="tagname:value"] Correspond au même élément de n’importe quel hôte du groupe ABC ayant les tags 'tagname:value'.
/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))] Correspond à des éléments similaires de n’importe quel hôte du groupe ABC ou DEF avec les tags respectifs.

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.

Si la clé d’élément d’un élément référencé est modifiée, le filtre doit être mis à jour manuellement.

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

Le paramètre second permet de spécifier la période pour l'agrégation. La période peut uniquement être exprimée en durée ; la quantité de valeurs (préfixée par #) n'est pas prise en charge.

Les symboles d'unités 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 est un paramètre facultatif (pris en charge depuis Zabbix 7.0) et peut être omise :

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

La période 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é de l'élément. Par exemple, si la valeur « bucket » dans myItem[aaa,0.2] est 0.2, 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 appliqué aux valeurs de l'élément (doit être placé entre guillemets doubles). Opérateurs pris en charge :
    eq - égal à
    ne - différent de
    gt - supérieur à
    ge - supérieur ou égal à
    lt - inférieur à
    le - inférieur ou égal à
    like - correspond si le motif est contenu (sensible à la casse)
    bitand - ET bit à bit
    regexp - correspondance sensible à la casse avec l'expression régulière indiquée dans pattern
    iregexp - correspondance insensible à la casse avec l'expression régulière indiquée dans pattern.
  • pattern est le motif requis (les arguments de type chaîne doivent être placés entre guillemets doubles) ; il est pris en charge si operator est spécifié dans le troisième paramètre.

Commentaires :

  • Les paramètres facultatifs operator ou pattern ne peuvent pas être laissés vides après une virgule ; ils doivent être entièrement omis.
  • Avec bitand comme troisième paramètre, le quatrième paramètre pattern peut être spécifié sous la forme de deux nombres séparés par « / » : number_to_compare_with/mask. count_foreach() calcule un « ET bit à bit » entre la valeur et le mask, puis compare le résultat à number_to_compare_with. Si le résultat de l'« ET bit à bit » est égal à number_to_compare_with, la valeur est comptabilisé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. Pour la mise en correspondance des expressions régulières, les valeurs flottantes sont toujours représentées avec 4 chiffres 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 la représentation binaire (utilisée par le serveur Zabbix) peut affecter le 4e chiffre décimal.

Consultez les 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.

Function Disabled host Unavailable host with data Unavailable host without data Disabled item Unsupported item Data retrieval error (SQL)
avg_foreach ignorer retourner la moyenne ignorer ignorer ignorer ignorer
bucket_rate_foreach ignorer retourner le taux du compartiment ignorer ignorer ignorer ignorer
count_foreach ignorer retourner le nombre 0 ignorer ignorer ignorer
exists_foreach ignorer 1 1 ignorer 1 n/a
last_foreach ignorer retourner la dernière valeur ignorer ignorer ignorer ignorer
max_foreach ignorer retourner le maximum ignorer ignorer ignorer ignorer
min_foreach ignorer retourner le minimum ignorer ignorer ignorer ignorer
sum_foreach ignorer retourner la somme ignorer ignorer ignorer ignorer

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