1 Funkcje Foreach

Przegląd

Funkcje foreach są używane w obliczeniach agregujących, aby zwrócić jedną zagregowaną wartość 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ść to średnia wartość historii wybranej pozycji, w określonym przedziale czasowym.

Filtr pozycji jest częścią składni używanej przez funkcje foreach. Użycie symboli wildcard jest obsługiwane w filtrze pozycji, dzięki czemu wymagane pozycje mogą być wybierane dość elastycznie.

Obsługiwane funkcje

Funkcja Opis
avg_foreach Zwraca średnią wartość dla każdej pozycji.
bucket_rate_foreach Zwraca pary (górna granica przedziału, wartość współczynnika) odpowiednie do użycia w funkcji histogram_quantile(), gdzie "górna granica przedziału" to wartość parametru klucza pozycji zdefiniowanego przez parametr <parameter number>.
count_foreach Zwraca liczbę wartości dla każdej pozycji.
exists_foreach Zwraca '1' dla każdej włączonej pozycji.
last_foreach Zwraca ostatnią wartość dla każdej pozycji.
max_foreach Zwraca maksymalną wartość dla każdej pozycji.
min_foreach Zwraca minimalną wartość dla każdej pozycji.
sum_foreach Zwraca sumę wartości dla każdej pozycji.

Składnia funkcji

Funkcje foreach obsługują dwa wspólne parametry: item filter (szczegóły poniżej) i time period:

foreach_function(item filter,time period)

Na przykład:

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

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

Zauważ, że niektóre funkcje obsługują dodatkowe parametry.

Składnia Item filter

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 znacznikach pozycji (jako wyrażenie)

Spacje są dozwolone tylko wewnątrz wyrażenia warunków.

Użycie symboli wildcard

  • Symbol wildcard może być użyty do zastąpienia nazwy hosta, klucza pozycji lub pojedynczego parametru klucza pozycji.
  • Zarówno nazwa hosta, jak i klucz pozycji muszą być określone bez symboli wildcard. Więc /host/* i /*/klucz są poprawnymi filtrami, ale /*/* jest nieprawidłowe.
  • Symbol wildcard nie może być używany dla części nazwy hosta, klucza pozycji ani parametru klucza pozycji.
  • Symbol wildcard nie pasuje do więcej niż pojedynczego parametru klucza pozycji. Więc symbol wildcard musi być określony dla każdego parametru osobno (tj. key[a,*,*]).

Wyrażenie warunków

Wyrażenie warunków obsługuje:

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

Użycie cudzysłowia dla stałych ciągów znaków jest obowiązkowe. Obsługiwane jest tylko pełne porównanie ciągów znaków z uwzględnieniem wielkości liter.

Przy określaniu znaczników w filtrze (tj. tag="tagname:value"), dwukropek ":" jest używany jako separator. Wszystko po nim traktowane jest jako wartość znacznika. Dlatego obecnie nie jest obsługiwane określanie nazwy znacznika zawierającej ":" w sobie.

Przykłady

Może być używany złożony filtr, odnoszący się do klucza pozycji, grupy hostów i znaczników, jak ilustrują przykłady:

Przykład składni Opis
/host/key[abc,*] Pasuje do podobnych pozycji na tym hoście.
/*/key Pasuje do tej samej pozycji na dowolnym hoście.
/*/key?[group="ABC" and tag="tagname:value"] Pasuje do tej samej pozycji na dowolnym hoście z grupy ABC mających znaczniki 'tagname:value'.
/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))] Pasuje do podobnych pozycji na dowolnym hoście z grupy ABC lub DEF z odpowiednimi znacznikami.

Wszystkie pozycje, do których istnieją odniesienia, muszą istnieć i zbierać dane. Tylko włączone pozycje na włączonych hostach są uwzględniane w obliczeniach.

Jeśli klucz pozycji odwołanej pozycji zostanie zmieniony, filtr musi być aktualizowany ręcznie.

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

Time period

Drugi parametr pozwala określić okres czasu dla agregacji. Okres czasu może być wyrażony tylko jako czas, ilość wartości (poprzedzonych #) nie jest obsługiwana.

Wspierane symbole jednostek mogą być używane w tym parametrze dla wygody, na przykład '5m' (pięć minut) zamiast '300s' (300 sekund) lub '1d' (jeden dzień) zamiast '86400' (86400 sekund).

Okres czasu jest ignorowany przez serwer, jeśli jest przekazany z funkcją last_foreach i może zostać pominięty:

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

Okres czasu nie jest obsługiwany w funkcji exists_foreach.

Dodatkowe parametry

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 "przedziału" w kluczu pozycji. Na przykład, jeśli wartość "przedziału" w myItem[aaa,0.2] to '0.2', to jej pozycją jest 2.

Domyślną wartością <parameter number> jest '1'.

Zobacz obliczenia agregujące po więcej szczegółów i przykłady dotyczące używania funkcji foreach.

Zachowanie w zależności od dostępności

Następująca tabela przedstawia, w jaki sposób każda funkcja zachowuje się w przypadkach ograniczonej dostępności hosta/pozycji oraz danych historycznych.

Funkcja Wyłączony host Niedostępny host z danymi Niedostępny host bez danych Wyłączona pozycja Niewspierana pozycja Błąd pobierania danych (SQL)
avg_foreach ignoruj zwróć średnią ignoruj ignoruj ignoruj ignoruj
bucket_rate_foreach ignoruj zwróć wartość przedziału ignoruj ignoruj ignoruj ignoruj
count_foreach ignoruj zwróć liczbę 0 ignoruj ignoruj ignoruj
exists_foreach ignoruj 1 1 ignoruj 1 n/d
last_foreach ignoruj zwróć ostatnią ignoruj ignoruj ignoruj ignoruj
max_foreach ignoruj zwróć maksimum ignoruj ignoruj ignoruj ignoruj
min_foreach ignoruj zwróć minimum ignoruj ignoruj ignoruj ignoruj
sum_foreach ignoruj zwróć sumę ignoruj ignoruj ignoruj ignoruj

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