Documentation
Table of Contents
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:
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:
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/*/kluczsą 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:
Okres czasu nie jest obsługiwany w funkcji exists_foreach.
Dodatkowe parametry
Trzeci opcjonalny parametr jest obsługiwany przez funkcję bucket_rate_foreach:
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.