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/*/keysont 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 danspattern
iregexp - correspondance insensible à la casse avec l'expression régulière indiquée danspattern. - 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
patternpeut ê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
patternpeut ê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.