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:

foreach_function(item filter,time period)

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:

 /host/key[parameters]?[conditions]

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 /*/key só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:

 last_foreach(/*/key?[group="grup d'equips"])

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:

 bucket_rate_foreach(filtre d'elements, període de temps, <nombre de paràmetre>)

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.