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).
El servidor ignora el període si es passa amb la funció last_foreach i, per tant, es pot ometre:
El període no s'admet amb la funció exists_foreach.
Paràmetres addicionals
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 "cub" a la clau de l'element. Per exemple, si el valor del "cub" 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'.
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.