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
| ¹ó³Ü²Ô³¦¾±¨® | ¶Ù±ð²õ³¦°ù¾±±è³¦¾±¨® |
|---|---|
| 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 ±è²¹°ù¨¤³¾±ð³Ù°ù±ð clau de l'element definit pel <nombre de ±è²¹°ù¨¤³¾±ð³Ù°ù±ð> ±è²¹°ù¨¤³¾±ð³Ù°ù±ð. |
| 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 ±è²¹°ù¨¤³¾±ð³Ù°ù±ðs 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 ±è²¹°ù¨¤³¾±ð³Ù°ù±ðs addicionals.
Sintaxi del filtre d'elements
El filtre d'elements:
consta de quatre parts, on:
- host - nom d'equip
- key - clau d'element (sense ±è²¹°ù¨¤³¾±ð³Ù°ù±ðs)
- parameters - ±è²¹°ù¨¤³¾±ð³Ù°ù±ðs 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 ±è²¹°ù¨¤³¾±ð³Ù°ù±ð 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 ±è²¹°ù¨¤³¾±ð³Ù°ù±ð de la clau d'element.
- El comod¨ª no ha de coincidir amb m¨¦s d'un ±è²¹°ù¨¤³¾±ð³Ù°ù±ð clau d'element. Per tant, s'ha d'especificar un comod¨ª per a cada ±è²¹°ù¨¤³¾±ð³Ù°ù±ð 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 | ¶Ù±ð²õ³¦°ù¾±±è³¦¾±¨® |
|---|---|
/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 ±è²¹°ù¨¤³¾±ð³Ù°ù±ð 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 ±è²¹°ù¨¤³¾±ð³Ù°ù±ð 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 Áú»¢¶Ä²© .0), per¨° es pot ometre:
El per¨ªode no s'admet amb la funci¨® exists_foreach.
Par¨¤metres addicionals
bucket_rate_foreach
Un tercer ±è²¹°ù¨¤³¾±ð³Ù°ù±ð opcional ¨¦s compatible amb la funci¨® bucket_rate_foreach:
on el <nombre de ±è²¹°ù¨¤³¾±ð³Ù°ù±ð> ¨¦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 ±è²¹°ù¨¤³¾±ð³Ù°ù±ð> ¨¦s '1'.
count_foreach
El tercer i quart ±è²¹°ù¨¤³¾±ð³Ù°ù±ðs 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 ±è²¹³Ù°ù¨® (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
- ±è²¹³Ù°ù¨® ¨¦s el ±è²¹³Ù°ù¨® requerit (els arguments de cadena han d'estar entre cometes); suportat si s'especifica operador al tercer ±è²¹°ù¨¤³¾±ð³Ù°ù±ð.
Comentaris:
- Els ±è²¹°ù¨¤³¾±ð³Ù°ù±ðs opcionals operador o ±è²¹³Ù°ù¨® no es poden deixar buits despr¨¦s d'una coma, nom¨¦s s'ometen completament.
- Amb bitand com a tercer ±è²¹°ù¨¤³¾±ð³Ù°ù±ð, el quart ±è²¹°ù¨¤³¾±ð³Ù°ù±ð
±è²¹³Ù°ù¨®es pot especificar com a dos n¨²meros, separats per '/': ²Ô´Ç³¾²ú°ù±ð³å²¹³å³¦´Ç³¾±è²¹°ù²¹°ù³å²¹³¾²ú/³¾¨¤²õ³¦²¹°ù²¹. count_foreach() calcula "AND bit a bit" a partir del valor i la ³¾¨¤²õ³¦²¹°ù²¹ i compara el resultat amb nombre_per_comparar_amb. Si el resultat de "AND bit a bit" ¨¦s igual a nombre_a_comparar_amb, es compta el valor.
Si nombre_a_comparar_amb i ³¾¨¤²õ³¦²¹°ù²¹ s¨®n iguals, nom¨¦s cal especificar la ³¾¨¤²õ³¦²¹°ù²¹ (sense '/'). - Amb regexp o iregexp com a tercer ±è²¹°ù¨¤³¾±ð³Ù°ù±ð, el quart ±è²¹°ù¨¤³¾±ð³Ù°ù±ð
patternpot 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 Áú»¢¶Ä²©) 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.
| ¹ó³Ü²Ô³¦¾±¨® | 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.