Documentation
Table of Contents
1 Funcions Foreach
Vista general
Les funcions de Foreach s'empren als càlculs agregats i retornen un valor agregat per cada element triat al **filtre d'element*. Es retorna una taula de valors.
per exemple, la funció avg_foreach retorna una taula de valors, on cada valor és la mitjana de valors històrics de l'element triat, durant l'interval de temps donat.
El filtre d'element és part de la sintaxi emprada per les funcions foreach. L'ús de comodins s'admet al filtre, per poder triar els elements desitjats de manera flexible.
Funcions admeses
| Funció | Descripció |
|---|---|
| avg_foreach | Retorna el valor mitjà de cada element. |
| bucket_rate_foreach | Retorna parells (límit superior del cub, valor de la taxa) que es poden emprar a la funció histograma_quantile(), on "límit superior del cub" és el valor del paràmetre clau de l'element definit pel <nombre de paràmetre> paràmetre. |
| count_foreach | Retorna el recompte de valors per a cada element. |
| exists_foreach | Retorna el nombre d'elements actualment actius. |
| last_foreach | Retorna el darrer valor de cada element. |
| max_foreach | Retorna el valor màxim per a cada element. |
| min_foreach | Retorna el valor mínim per a cada element. |
| sum_foreach | Retorna la suma de valors per a cada element. |
Sintaxi de la funció
Les funcions Foreach admeten dos paràmetres comuns: filtre de l'element (veieu els detalls a sota) i període de temps:
Per exemple:
avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)
retorna la mitjana de cinc minuts de cada element 'mysql.qps' del grup de servidors MySQL.
Veieu que algunes funcions admeten paràmetres addicionals.
Sintaxi del filtre d'elements
El filtre d'elements:
consta de quatre parts, on:
- host - nom d'equip
- key - clau d'element (sense paràmetres)
- parameters - paràmetres clau de l'element
- conditions - condicions basades en el grup d'equips i/o l'etiqueta d'element (com a expressió)
Els espais només es permeten dins de l'expressió de condicions.
Ús del comodí
- El comodí es pot emprar per substituir el nom d'equip, la clau d'element o un paràmetre de clau d'element individual.
- S'ha d'especificar l'equip o la clau de l'element sense comodí. Per tant,
/host/*i/*/keysón filtres vàlids, però/*/*no és vàlid. - El comodí no es pot emprar per a una part del nom d'equip, la clau d'element o el paràmetre de la clau d'element.
- El comodí no ha de coincidir amb més d'un paràmetre clau d'element. Per tant, s'ha d'especificar un comodí per a cada paràmetre separat (és a dir,
key[abc,*,*]).
Expressió de condicions
L'expressió de condicions admet:
- operands:
- group - grup d'equips
- tag - etiqueta d'element
"<text>"- constant de cadena, amb el caràcter d'escapada\per escapar"i\
- Operadors de comparació de cadenes que distingeixen entre majúscules i minúscules:
=,<> - operadors lògics:
i,o,no - agrupació amb parèntesis:
()
La citació de les constants de cadena és obligatòria. Només s'admet la comparació de cadenes completes que distingeix entre majúscules i minúscules.
Quan especifiquem les etiquetes al filtre, (p.e. tag="tagname:value"), s'empra com a delimitador els dos punts ":". Qualsevol cosa després d'aquest es considera el valor d'etiqueta. Per això, no s'admet cap nom d'etiqueta que contingui ":".
Exemples
Es pot emprar un filtre complex, fent referència a la clau de l'element, el grup d'equips i etiquetes, tal com ho il·lustren els exemples:
| Exemple de sintaxi | Descripció |
|---|---|
/host/key[abc,*] |
Coincideix amb elements similars en aquest equip. |
/*/key |
Coincideix amb el mateix element de qualsevol equip. |
/*/key?[group="ABC" and tag="tagname:value"] |
Coincideix amb el mateix element de qualsevol equip del grup ABC que tingui etiquetes 'tagname:value'. |
/*/key[a,*,c]?[(group="ABC" i tag="Tag1") o (group="DEF" i (tag="Tag2" o tag="Tag3:value" ))] |
Fa coincidir elements similars de qualsevol equip del grup ABC o DEF amb les etiquetes respectives. |
Tots els elements referenciats han d'existir i recollir dades. Només els elements activats dels hosts habilitats s'inclouran als càlculs.
Si es canvia la clau d'element d'un element de referència, el filtre s'ha d'actualitzar manualment.
L'especificació d'un grup d'equips principal inclou el grup principal i tots els grups descendents amb els seus articles.
Període de temps
El segon paràmetre s'empra per especificar el període de temps per a l'agregació. El període de temps només es pot expressar en temps, la quantitat de valors (prefixada amb #) no s'admet.
Es poden emprar els símbols d'unitat admesos en aquest paràmetre per comoditat, per exemple, '5m' (cinc minuts) en lloc de '300s' (300 segons) o '1d' (un dia) en lloc de '86400' (86400 segons).
La funció de període de temps last_foreach és opcional (admesa des de Zabbix .0), però es pot ometre:
El període no s'admet amb la funció exists_foreach.
Paràmetres addicionals
bucket_rate_foreach
Un tercer paràmetre opcional és compatible amb la funció bucket_rate_foreach:
on el <nombre de paràmetre> és la posició del valor del "bucket" a la clau de l'element. Per exemple, si el valor del "bucket" a myItem[aaa,0.2] és '0,2', aleshores la seva posició és 2.
El valor per defecte del <nombre de paràmetre> és '1'.
count_foreach
El tercer i quart paràmetres opcionals s'admeten amb la funció count_foreach:
count_foreach(item filter,time period,<operator>,<pattern>)
On:
- operador és l'operador condicional per als valors d'element (ha d'estar entre cometes dobles). "Operadors" admesos:
eq - igual
ne - no igual
gt - major
ge - major o igual
lt - menys<br >le - menor o igual
com - coincideix si conté un patró (distingeix entre majúscules i minúscules)
bitand - per bits AND
regexp - coincideix amb majúscules i minúscules de l'expressió regular donada apattern
iregexp: coincidència sense distinció entre majúscules i minúscules de l'expressió regular donada apattern
- patró és el patró requerit (els arguments de cadena han d'estar entre cometes); suportat si s'especifica operador al tercer paràmetre.
Comentaris:- Els paràmetres opcionals operador o patró no es poden deixar buits després d'una coma, només s'ometen completament.- Amb bitand com a tercer paràmetre, el quart paràmetre patró es pot especificar com a dos números, separats per '/': número_a_comparar_amb/màscara. count() calcula "AND bit a bit" a partir del valor i la màscara i compara el resultat amb número_per_comparar_amb. Si el resultat de "AND bit a bit" és igual a nombre_a_comparar_amb, es compta el valor.
Si número_a_comparar_amb i màscara són iguals, només cal especificar la màscara (sense '/').- Amb regexp o iregexp com a tercer paràmetre, el quart paràmetre pattern pot ser una expressió regular ordinària o global (començant per '@'). En el cas de les expressions regulars globals, la distinció entre majúscules i minúscules s'hereta de la configuració global de les expressions regulars. Per a la concordança d'expressions regulars, els valors flotants sempre es representaran amb 4 dígits decimals després de ".". Tingueu en compte també que, per a nombres grans, la diferència de representació decimal (emmagatzemat a la base de dades) i binària (utilitzada pel servidor Zabbix) pot afectar el quart dígit decimal.
Veieu càlculs agregats per a més detalls i exemples sobre com emprar les funcions foreach.
Comportament depenent de la disponibilitat
La taula següent ensenya com es comporta cada funció en cas de disponibilitat limitada de l'equip/element i històric.
| Funció | Equip deshabilitat | Equip no disponible amb informació | Equip no disponible sense informació | Element deshabilitat | Element no admès | Error SQL de recuperació d'informació |
|---|---|---|---|---|---|---|
| avg_foreach | ignorar | retorna avg | ignorar | ignorar | ignorar | ignorar |
| bucket_rate_foreach | ignorar | retorna bucket rate | ignorar | ignorar | ignorar | ignorar |
| count_foreach | ignorar | retorna count | 0 | ignorar | ignorar | ignorar |
| exists_foreach | ignorar | 1 | 1 | ignorar | 1 | n/a |
| last_foreach | ignorar | retorna last | ignorar | ignorar | ignorar | ignorar |
| max_foreach | ignorar | retorna max | ignorar | ignorar | ignorar | ignorar |
| min_foreach | ignorar | retorna min | ignorar | ignorar | ignorar | ignorar |
| sum_foreach | ignorar | retorna sum | ignorar | ignorar | ignorar | ignorar |
Si l'element s'ha ignorat, no s'afegirà pas res.