Funkcje foreach

Przegląd

Funkcje foreach są używane w obliczeniach agregujących do zwracania jednej wartości zagregowanej dla każdej pozycji wybranej przez użyty filtr pozycji. Zwracana jest tablica wartości.

Na przykład funkcja avg_foreach zwróci tablicę wartości, gdzie każda wartość jest średnią wartością historyczną wybranej pozycji w określonym przedziale czasu.

Filtr pozycji jest częścią składni używanej przez funkcje foreach. W filtrze pozycji obsługiwane jest użycie symboli wieloznacznych, dzięki czemu wymagane pozycje można wybierać w bardzo elastyczny sposób.

Obsługiwane funkcje

Składnia funkcji

Funkcje foreach obsługują dwa wspólne parametry: filtr pozycji (szczegóły poniżej) oraz okres czasu:

foreach_function(item filter,time period)

Na przykład:

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

zwróci pięciominutową średnią dla każdej pozycji „mysql.qps” w grupie serwerów MySQL.

Należy pamiętać, że niektóre funkcje obsługują dodatkowe parametry.

Składnia filtra pozycji

Filtr pozycji:

/host/key[parameters]?[conditions]

składa się z czterech części, gdzie:

• host - nazwa hosta
• key - klucz pozycji (bez parametrów)
• parameters - parametry klucza pozycji
• conditions - warunki oparte na grupie hostów i/lub tagach pozycji (w postaci wyrażenia)

Spacje są dozwolone wyłącznie wewnątrz wyrażenia warunków.

Użycie symbolu wieloznacznego

• Symbol wieloznaczny może być użyty do zastąpienia nazwy hosta, klucza pozycji lub pojedynczego parametru klucza pozycji.
• Albo host, albo klucz pozycji musi być określony bez symbolu wieloznacznego. Dlatego /host/* i /*/key są poprawnymi filtrami, ale /*/* jest nieprawidłowy.
• Symbol wieloznaczny nie może być użyty dla części nazwy hosta, klucza pozycji ani parametru klucza pozycji.
• Symbol wieloznaczny nie dopasowuje więcej niż jednego parametru klucza pozycji. Dlatego symbol wieloznaczny musi być określony osobno dla każdego parametru (tj. key[abc,*,*]).

Wyrażenie warunków

Wyrażenie warunków obsługuje:

• operandy:
  • group - grupa hostów
  • tag - tag pozycji
  • "<text>" - stała tekstowa, ze znakiem ucieczki \ do poprzedzania " i \
• operatory porównania ciągów znaków z rozróżnianiem wielkości liter: =, <>
• operatory logiczne: and, or, not
• grupowanie za pomocą nawiasów: ( )

Ujęcie stałych tekstowych w cudzysłów jest obowiązkowe. Obsługiwane jest tylko pełne porównanie ciągów znaków z rozróżnianiem wielkości liter.

Przykłady

Można użyć złożonego filtra odwołującego się do klucza pozycji, grupy hostów i tagów, co ilustrują poniższe przykłady:

Wszystkie pozycje, do których istnieją odwołania, muszą istnieć i zbierać dane. W obliczeniach uwzględniane są tylko włączone pozycje na włączonych hostach. Pozycje w stanie nieobsługiwanym nie są uwzględniane.

Określenie nadrzędnej grupy hostów obejmuje grupę nadrzędną oraz wszystkie zagnieżdżone grupy hostów wraz z ich pozycjami.

Okres czasu

Drugi parametr pozwala określić okres czasu dla agregacji. Okres czasu może być wyrażony wyłącznie jako czas; liczba wartości (poprzedzona prefiksem #) nie jest obsługiwana.

Dla wygody w tym parametrze można używać obsługiwanych symboli jednostek, na przykład „5m” (pięć minut) zamiast „300s” (300 sekund) lub „1d” (jeden dzień) zamiast „86400” (86400 sekund).

W przypadku funkcji last_foreach okres czasu jest parametrem opcjonalnym (obsługiwanym od Zabbix 7.0), który można pominąć:

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

Okres czasu nie jest obsługiwany przez funkcję exists_foreach.

Dodatkowe parametry

bucket_rate_foreach

Trzeci opcjonalny parametr jest obsługiwany przez funkcję bucket_rate_foreach:

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

gdzie <parameter number> to pozycja wartości „bucket” w kluczu pozycji. Na przykład, jeśli wartość „bucket” w myItem[aaa,0.2] to „0.2”, to jej pozycja wynosi 2.

Domyślna wartość <parameter number> to „1”.

count_foreach

Trzeci i czwarty opcjonalny parametr są obsługiwane przez funkcję count_foreach:

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

Gdzie:

• operator to operator warunkowy dla wartości pozycji (musi być ujęty w podwójny cudzysłów). Obsługiwane operators:
  eq - równe
  ne - nierówne
  gt - większe
  ge - większe lub równe
  lt - mniejsze
  le - mniejsze lub równe
  like - pasuje, jeśli zawiera wzorzec (z rozróżnianiem wielkości liter)
  bitand - bitowe AND
  regexp - dopasowanie z rozróżnianiem wielkości liter do wyrażenia regularnego podanego w pattern
  iregexp - dopasowanie bez rozróżniania wielkości liter do wyrażenia regularnego podanego w pattern
  
• pattern to wymagany wzorzec (argumenty tekstowe muszą być ujęte w podwójny cudzysłów); obsługiwany, jeśli operator jest określony w trzecim parametrze.

Uwagi:

• Opcjonalnych parametrów operator lub pattern nie można pozostawić pustych po przecinku, można je tylko całkowicie pominąć.
• Gdy jako trzeci parametr użyto bitand, czwarty parametr pattern można określić jako dwie liczby rozdzielone znakiem '/': number_to_compare_with/mask. count_foreach() oblicza „bitowe AND” z wartości i mask oraz porównuje wynik z number_to_compare_with. Jeśli wynik „bitowego AND” jest równy number_to_compare_with, wartość jest zliczana.
  Jeśli number_to_compare_with i mask są równe, wystarczy podać tylko mask (bez '/').
• Gdy jako trzeci parametr użyto regexp lub iregexp, czwarty parametr pattern może być zwykłym lub globalnym (zaczynającym się od '@') wyrażeniem regularnym. W przypadku globalnych wyrażeń regularnych rozróżnianie wielkości liter jest dziedziczone z ustawień globalnych wyrażeń regularnych. Na potrzeby dopasowania regexp wartości zmiennoprzecinkowe będą zawsze przedstawiane z 4 cyframi dziesiętnymi po '.'. Należy również pamiętać, że w przypadku dużych liczb różnica między reprezentacją dziesiętną (przechowywaną w bazie danych) a binarną (używaną przez serwer Zabbix) może wpływać na 4. cyfrę dziesiętną.

Więcej szczegółów i przykładów użycia funkcji foreach można znaleźć w sekcji obliczenia agregowane.

Zachowanie zależne od dostępności

Poniższa tabela ilustruje, jak każda funkcja zachowuje się w przypadkach ograniczonej dostępności hosta/pozycji oraz danych historycznych.

Jeśli pozycja jest ignorowana, nic nie jest dodawane do agregacji.