Le funzioni foreach sono utilizzate nei calcoli aggregati per restituire un valore aggregato per ciascun item selezionato dal filtro item utilizzato. Viene restituito un array di valori.

Le funzioni foreach sono supportate solo all'interno dei Calculated item come parte delle formule di calcolo aggregato. Non possono essere richiamate in semplici chiavi item o in espressioni trigger al di fuori di questo contesto.

Ad esempio, la funzione avg_foreach restituirà un array di valori, in cui ciascun valore è il valore storico medio dell'item selezionato, durante l'intervallo di tempo specificato.

Il filtro item fa parte della sintassi utilizzata dalle funzioni foreach. Nel filtro item è supportato l'uso dei caratteri jolly, pertanto gli item richiesti possono essere selezionati in modo piuttosto flessibile.

Funzioni supportate

Function	Description
avg_foreach	Restituisce il valore medio per ciascun item.
bucket_rate_foreach	Restituisce coppie (limite superiore del bucket, valore del rate) adatte all'uso nella funzione histogram_quantile(), dove il "limite superiore del bucket" è il valore del parametro della chiave item definito dal parametro <parameter number>.
count_foreach	Restituisce il numero di valori per ciascun item.
exists_foreach	Restituisce '1' per ciascun item abilitato.
last_foreach	Restituisce l'ultimo valore per ciascun item.
max_foreach	Restituisce il valore massimo per ciascun item.
min_foreach	Restituisce il valore minimo per ciascun item.
sum_foreach	Restituisce la somma dei valori per ciascun item.

Sintassi della funzione

Le funzioni foreach supportano due parametri comuni: filtro item (vedi i dettagli sotto) e periodo di tempo:

foreach_function(item filter,time period)

Per esempio:

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

restituirà la media su cinque minuti di ciascun item 'mysql.qps' nel gruppo di server MySQL.

Si noti che alcune funzioni supportano parametri aggiuntivi.

Sintassi del filtro item

Il filtro item:

/host/key[parameters]?[conditions]

è composto da quattro parti, dove:

host - nome del host
key - chiave dell'item (senza parametri)
parameters - parametri della chiave dell'item
conditions - condizioni basate sul gruppo host e/o sui tag dell'item (come espressione)

Gli spazi sono consentiti solo all'interno dell'espressione delle condizioni.

Uso dei caratteri jolly

Il carattere jolly può essere utilizzato per sostituire il nome del host, la chiave dell'item o un singolo parametro della chiave dell'item.
Il host oppure la chiave dell'item deve essere specificato senza carattere jolly. Quindi /host/* e /*/key sono filtri validi, ma /*/* non è valido.
Il carattere jolly non può essere utilizzato per una parte del nome del host, della chiave dell'item o del parametro della chiave dell'item.
Il carattere jolly non corrisponde a più di un singolo parametro della chiave dell'item. Pertanto, deve essere specificato un carattere jolly per ciascun parametro separatamente (ad esempio key[abc,*,*]).

Espressione delle condizioni

L'espressione delle condizioni supporta:

operandi:
- group - gruppo host
- tag - tag dell'item
- "<text>" - costante stringa, con il carattere di escape \ per eseguire l'escape di " e \
operatori di confronto tra stringhe con distinzione tra maiuscole e minuscole: =, <>
operatori logici: and, or, not
raggruppamento con parentesi: ( )

Le virgolette per le costanti stringa sono obbligatorie. È supportato solo il confronto completo tra stringhe con distinzione tra maiuscole e minuscole.

Quando si specificano i tag nel filtro (ad esempio tag="tagname:value"), i due punti ":" vengono utilizzati come delimitatore. Tutto ciò che segue viene considerato il valore del tag. Pertanto, attualmente non è supportato specificare un nome tag che contenga ":".

Esempi

Può essere utilizzato un filtro complesso che fa riferimento alla chiave dell'item, al gruppo host e ai tag, come illustrato negli esempi:

Syntax example	Description
`/host/key[abc,*]`	Corrisponde a item simili su questo host.
`/*/key`	Corrisponde allo stesso item di qualsiasi host.
`/*/key?[group="ABC" and tag="tagname:value"]`	Corrisponde allo stesso item di qualsiasi host del gruppo ABC che abbia tag 'tagname:value'.
`//key[a,,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))]`	Corrisponde a item simili di qualsiasi host del gruppo ABC o DEF con i rispettivi tag.

Tutti gli item referenziati devono esistere e raccogliere dati. Solo gli item abilitati su host abilitati sono inclusi nei calcoli. Gli item nello stato unsupported non sono inclusi.

Se la chiave dell'item di un item referenziato viene modificata, il filtro deve essere aggiornato manualmente.

La specifica di un gruppo host padre include il gruppo padre e tutti i gruppi host nidificati con i relativi item.

Periodo di tempo

Il secondo parametro consente di specificare il periodo di tempo per l'aggregazione. Il periodo di tempo può essere espresso solo come tempo; la quantità di valori (preceduta da #) non è supportata.

In questo parametro, per comodità, è possibile utilizzare i simboli di unità supportati, ad esempio '5m' (cinque minuti) invece di '300s' (300 secondi) oppure '1d' (un giorno) invece di '86400' (86400 secondi).

Per la funzione last_foreach, il periodo di tempo è un parametro facoltativo (supportato da Zabbix 7.0), che può essere omesso:

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

Il periodo di tempo non è supportato con la funzione exists_foreach.

Parametri aggiuntivi

bucket_rate_foreach

Un terzo parametro opzionale è supportato dalla funzione bucket_rate_foreach:

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

dove <parameter number> è la posizione del valore "bucket" nella chiave item. Ad esempio, se il valore "bucket" in myItem[aaa,0.2] è '0.2', allora la sua posizione è 2.

Il valore predefinito di <parameter number> è '1'.

count_foreach

Il terzo e il quarto parametro opzionale sono supportati dalla funzione count_foreach:

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

Dove:

operator è l'operatore condizionale per i valori dell'item (deve essere tra doppi apici). operatori supportati:
eq - uguale
ne - diverso
gt - maggiore
ge - maggiore o uguale
lt - minore
le - minore o uguale
like - corrisponde se contiene il pattern (con distinzione tra maiuscole e minuscole)
bitand - AND bit a bit
regexp - corrispondenza con distinzione tra maiuscole e minuscole dell'espressione regolare fornita in pattern
iregexp - corrispondenza senza distinzione tra maiuscole e minuscole dell'espressione regolare fornita in pattern
pattern è il pattern richiesto (gli argomenti stringa devono essere tra doppi apici); supportato se operator è specificato nel terzo parametro.

Commenti:

I parametri opzionali operator o pattern non possono essere lasciati vuoti dopo una virgola, possono solo essere omessi completamente.
Con bitand come terzo parametro, il quarto parametro pattern può essere specificato come due numeri, separati da '/': number_to_compare_with/mask. count_foreach() calcola l'"AND bit a bit" dal valore e dalla mask e confronta il risultato con number_to_compare_with. Se il risultato dell'"AND bit a bit" è uguale a number_to_compare_with, il valore viene conteggiato.
Se number_to_compare_with e mask sono uguali, è necessario specificare solo la mask (senza '/').
Con regexp o iregexp come terzo parametro, il quarto parametro pattern può essere un'espressione regolare ordinaria o globale (che inizia con '@'). Nel caso di espressioni regolari globali, la distinzione tra maiuscole e minuscole viene ereditata dalle impostazioni delle espressioni regolari globali. Ai fini della corrispondenza regexp, i valori float saranno sempre rappresentati con 4 cifre decimali dopo '.'. Si noti inoltre che per numeri grandi la differenza tra la rappresentazione decimale (memorizzata nel database) e quella binaria (utilizzata da Zabbix server) può influire sulla quarta cifra decimale.

Vedere calcoli aggregati per maggiori dettagli ed esempi sull'uso delle funzioni foreach.

Comportamento in base alla disponibilità

La tabella seguente illustra come si comporta ciascuna funzione nei casi di disponibilità limitata di host/item e dei dati di storico.

Function	Host disabilitato	Host non disponibile con dati	Host non disponibile senza dati	Item disabilitato	Item non supportato	Errore di recupero dati (SQL)
avg_foreach	ignora	restituisce avg	ignora	ignora	ignora	ignora
bucket_rate_foreach	ignora	restituisce bucket rate	ignora	ignora	ignora	ignora
count_foreach	ignora	restituisce count	0	ignora	ignora	ignora
exists_foreach	ignora	1	1	ignora	1	n/d
last_foreach	ignora	restituisce last	ignora	ignora	ignora	ignora
max_foreach	ignora	restituisce max	ignora	ignora	ignora	ignora
min_foreach	ignora	restituisce min	ignora	ignora	ignora	ignora
sum_foreach	ignora	restituisce sum	ignora	ignora	ignora	ignora

Se l'item viene ignorato, non viene aggiunto nulla all'aggregazione.

What’s next?

2 Funzioni bit a bit

Docs

Funzioni foreach

Panoramica