Foreach funkcijas

Pārskats

Foreach funkcijas tiek izmantotas apkoptajos aprēķinos, lai katram vienumam, kas ir atlasīts ar izmantoto vienumu filtru, atgrieztu vienu apkopotu vērtību. Tiek atgriezts vērtību masīvs.

Foreach funkcijas tiek atbalstītas tikai aprēķinātajos vienumos kā daļa no apkopoto aprēķinu formulām. Tās nevar izsaukt parastās vienumu atslēgās vai trigeru izteiksmēs ārpus šī konteksta.

Piemēram, funkcija avg_foreach atgriezīs vērtību masīvu, kur katra vērtība ir atlasītā vienuma vēstures vērtību vidējā vērtība norādītajā laika intervālā.

item filter ir daļa no sintakses, ko izmanto foreach funkcijas. Vienumu filtrā tiek atbalstīta aizstājējzīmju izmantošana, tādējādi nepieciešamos vienumus var atlasīt ļoti elastīgi.

Atbalstītās funkcijas

Function Description
avg_foreach Atgriež katra vienuma vidējo vērtību.
bucket_rate_foreach Atgriež pārus (groza augšējā robeža, ātruma vērtība), kas ir piemēroti izmantošanai funkcijā histogram_quantile(), kur "groza augšējā robeža" ir vienuma atslēgas parametra vērtība, kas definēta <parameter number> parametrā.
count_foreach Atgriež vērtību skaitu katram vienumam.
exists_foreach Atgriež '1' katram iespējotam vienumam.
last_foreach Atgriež katra vienuma pēdējo vērtību.
max_foreach Atgriež katra vienuma maksimālo vērtību.
min_foreach Atgriež katra vienuma minimālo vērtību.
sum_foreach Atgriež vērtību summu katram vienumam.

Funkcijas sintakse

Foreach funkcijas atbalsta divus kopīgus parametrus: vienuma filtrs (skatiet detalizētu informāciju zemāk) un laika periods:

foreach_function(item filter,time period)

Piemēram:

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

atgriezīs katra 'mysql.qps' vienuma piecu minūšu vidējo vērtību MySQL serveru grupā.

Ņemiet vērā, ka dažas funkcijas atbalsta papildu parametrus.

Vienumu filtra sintakse

Vienumu filtrs:

/host/key[parameters]?[conditions]

sastāv no četrām daļām, kur:

  • host - hosta nosaukums
  • key - vienuma atslēga (bez parametriem)
  • parameters - vienuma atslēgas parametri
  • conditions - uz hostu grupu un/vai vienuma tagu balstīti nosacījumi (izteiksmes veidā)

Atstarpes ir atļautas tikai nosacījumu izteiksmē.

Aizstājējzīmju lietošana

  • Aizstājējzīmi var izmantot, lai aizstātu hosta nosaukumu, vienuma atslēgu vai atsevišķu vienuma atslēgas parametru.
  • Vai nu hostam, vai vienuma atslēgai jābūt norādītai bez aizstājējzīmes. Tātad /host/* un /*/key ir derīgi filtri, bet /*/* ir nederīgs.
  • Aizstājējzīmi nevar izmantot hosta nosaukuma, vienuma atslēgas vai vienuma atslēgas parametra daļai.
  • Aizstājējzīme neatbilst vairāk nekā vienam vienuma atslēgas parametram. Tāpēc aizstājējzīme jānorāda katram parametram atsevišķi (t.i., key[abc,*,*]).

Nosacījumu izteiksme

Nosacījumu izteiksme atbalsta:

  • operandus:
    • group - hostu grupa
    • tag - vienuma tags
    • "<text>" - virknes konstante ar \ atsoļa rakstzīmi, lai atsoļotu " un \
  • reģistrjutīgus virkņu salīdzināšanas operatorus: =, <>
  • loģiskos operatorus: and, or, not
  • grupēšanu ar iekavām: ( )

Virkņu konstanšu pēdiņas ir obligātas. Tiek atbalstīta tikai pilnas virknes salīdzināšana ar reģistrjutību.

Norādot tagus filtrā (t.i. tag="tagname:value"), kols ":" tiek izmantots kā atdalītājs. Viss pēc tā tiek uzskatīts par taga vērtību. Tādēļ pašlaik netiek atbalstīta tāda taga nosaukuma norādīšana, kas satur ":".

Piemēri

Var izmantot sarežģītu filtru, atsaucoties uz vienuma atslēgu, hostu grupu un tagiem, kā parādīts piemēros:

Sintakses piemērs Apraksts
/host/key[abc,*] Atbilst līdzīgiem vienumiem šajā hostā.
/*/key Atbilst vienam un tam pašam vienumam jebkurā hostā.
/*/key?[group="ABC" and tag="tagname:value"] Atbilst vienam un tam pašam vienumam jebkurā hostā no ABC grupas ar tagiem 'tagname:value'.
/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))] Atbilst līdzīgiem vienumiem jebkurā hostā no ABC vai DEF grupas ar attiecīgajiem tagiem.

Visiem norādītajiem vienumiem jāeksistē un jāvāc dati. Aprēķinos tiek iekļauti tikai iespējoti vienumi iespējotos hostos. Vienumi neatbalstītā stāvoklī netiek iekļauti.

Ja atsauktā vienuma atslēga tiek mainīta, filtrs ir jāatjaunina manuāli.

Norādot vecākgrupas hostu grupu, tiek iekļauta vecākgrupa un visas ligzdotās hostu grupas ar to vienumiem.

Laika periods

Otrais parametrs ļauj norādīt laika periodu agregācijai. Laika periodu var izteikt tikai kā laiku; vērtību skaits (ar prefiksu #) netiek atbalstīts.

Ērtības labad šajā parametrā var izmantot atbalstītos vienību simbolus, piemēram, '5m' (piecas minūtes) '300s' (300 sekundes) vietā vai '1d' (viena diena) '86400' (86400 sekundes) vietā.

Funkcijai last_foreach laika periods ir neobligāts parametrs (atbalstīts kopš Zabbix 7.0), kuru var izlaist:

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

Laika periods netiek atbalstīts ar funkciju exists_foreach.

Papildu parametri

bucket_rate_foreach

Trešo neobligāto parametru atbalsta funkcija bucket_rate_foreach:

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

kur <parameter number> ir "bucket" vērtības pozīcija vienuma atslēgā. Piemēram, ja "bucket" vērtība myItem[aaa,0.2] ir '0.2', tad tās pozīcija ir 2.

Noklusējuma vērtība parametram <parameter number> ir '1'.

count_foreach

Trešo un ceturto neobligāto parametru atbalsta funkcija count_foreach:

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

Kur:

  • operator ir nosacījuma operators vienuma vērtībām (jābūt dubultpēdiņās). Atbalstītie operators:
    eq - vienāds
    ne - nav vienāds
    gt - lielāks
    ge - lielāks vai vienāds
    lt - mazāks
    le - mazāks vai vienāds
    like - atbilst, ja satur šablonu (reģistrjutīgs)
    bitand - bitu AND
    regexp - reģistrjutīga atbilstība regulārajai izteiksmei, kas norādīta pattern
    iregexp - reģistrnejutīga atbilstība regulārajai izteiksmei, kas norādīta pattern
  • pattern ir obligātais šablons (virknes argumentiem jābūt dubultpēdiņās); tiek atbalstīts, ja operator ir norādīts trešajā parametrā.

Komentāri:

  • Neobligātos parametrus operator vai pattern nevar atstāt tukšus aiz komata, tos var tikai pilnībā izlaist.
  • Ja kā trešais parametrs ir bitand, ceturto pattern parametru var norādīt kā divus skaitļus, kas atdalīti ar '/': number_to_compare_with/mask. count_foreach() aprēķina "bitwise AND" no vērtības un mask un salīdzina rezultātu ar number_to_compare_with. Ja "bitwise AND" rezultāts ir vienāds ar number_to_compare_with, vērtība tiek ieskaitīta.
    Ja number_to_compare_with un mask ir vienādi, jānorāda tikai mask (bez '/').
  • Ja kā trešais parametrs ir regexp vai iregexp, ceturtais pattern parametrs var būt parasta vai globāla (sākas ar '@') regulārā izteiksme. Globālo regulāro izteiksmju gadījumā reģistrjutība tiek mantota no globālās regulārās izteiksmes iestatījumiem. Regexp atbilstības vajadzībām peldošā komata vērtības vienmēr tiks attēlotas ar 4 zīmēm aiz '.'. Ņemiet vērā arī to, ka lieliem skaitļiem atšķirība starp decimālo (glabājas datubāzē) un bināro (izmanto Zabbix serveris) attēlojumu var ietekmēt 4. zīmi aiz komata.

Plašāku informāciju un foreach funkciju lietošanas piemērus skatiet sadaļā agregētie aprēķini.

Darbība atkarībā no pieejamības

Tālāk esošā tabula parāda, kā katra funkcija darbojas ierobežotas hosta/vienuma un vēstures datu pieejamības gadījumos.

Function Disabled host Unavailable host with data Unavailable host without data Disabled item Unsupported item Data retrieval error (SQL)
avg_foreach ignorēt atgriezt vidējo ignorēt ignorēt ignorēt ignorēt
bucket_rate_foreach ignorēt atgriezt bucket rate ignorēt ignorēt ignorēt ignorēt
count_foreach ignorēt atgriezt skaitu 0 ignorēt ignorēt ignorēt
exists_foreach ignorēt 1 1 ignorēt 1 n/a
last_foreach ignorēt atgriezt pēdējo vērtību ignorēt ignorēt ignorēt ignorēt
max_foreach ignorēt atgriezt maksimumu ignorēt ignorēt ignorēt ignorēt
min_foreach ignorēt atgriezt minimumu ignorēt ignorēt ignorēt ignorēt
sum_foreach ignorēt atgriezt summu ignorēt ignorēt ignorēt ignorēt

Ja vienums tiek ignorēts, agregācijai nekas netiek pievienots.