PromQL w praktyce – jak analizować metryki Prometheusa i tworzyć zaawansowane zapytania?
Praktyczny przewodnik po PromQL: od selektorów i etykiet po agregacje, łączenie serii i percentyle latencji. Poznaj przykłady analizy CPU, pamięci i błędów oraz sposoby debugowania zapytań w Prometheusie i Grafanie.
Wprowadzenie do PromQL: metryki, serie czasowe i typy danych
PromQL, czyli Prometheus Query Language, służy do odczytywania i analizowania metryk przechowywanych w Prometheusie. Pozwala przejść od pojedynczych pomiarów do odpowiedzi na konkretne pytania: czy obciążenie usługi rośnie, ile żądań kończy się błędem i czy czas odpowiedzi pozostaje akceptowalny. Wyniki zapytań można wykorzystywać w interfejsie Prometheusa, na dashboardach Grafany oraz w regułach alertowania.
Podstawą pracy z PromQL jest zrozumienie, co reprezentuje seria czasowa i jaki typ danych zwraca wyrażenie. Bez tego nawet poprawne składniowo zapytanie może prowadzić do błędnych wniosków — na przykład wtedy, gdy narastającą liczbę żądań potraktujemy jako ich bieżące natężenie.
Metryka, seria czasowa i próbka — trzy różne pojęcia
Metryka opisuje mierzoną wielkość, na przykład zużycie pamięci, liczbę obsłużonych żądań albo czas ich przetwarzania. Jej nazwa wskazuje, czego dotyczy pomiar, a etykiety dodają kontekst: identyfikują instancję aplikacji, środowisko czy rodzaj odpowiedzi.
Serię czasową identyfikuje nazwa metryki wraz z kompletnym zestawem etykiet i ich wartości. Ta sama metryka zbierana z dwóch instancji aplikacji tworzy więc odrębne serie. Zmiana wartości dowolnej etykiety również oznacza inną serię, a nie aktualizację opisu istniejącej. Ma to znaczenie dla liczby przechowywanych serii, nazywanej kardynalnością. Etykiety zawierające identyfikatory użytkowników lub żądań mogą powodować jej gwałtowny wzrost.
Każda seria składa się z próbek, czyli wartości przypisanych do znaczników czasu. Prometheus zwykle zbiera je podczas cyklicznego odpytywania monitorowanych celów. Nie jest to zatem ciągły zapis każdej zmiany ani rejestr pojedynczych zdarzeń. Częstotliwość zbierania danych wpływa na szczegółowość obserwacji, a brak próbki nie oznacza automatycznie wartości zero.
Podstawowe typy metryk i ich zastosowania
Typ metryki określa sposób interpretacji pomiaru. W instrumentacji aplikacji spotkasz przede wszystkim cztery rodzaje:
- Counter — licznik. Rejestruje narastającą liczbę zdarzeń, na przykład żądań lub błędów. Jego wartość rośnie, ale może zostać wyzerowana, choćby po restarcie procesu. Do oceny bieżącej aktywności istotna jest zmiana licznika w czasie, nie sam jego stan.
- Gauge — wartość bieżąca. Może rosnąć i maleć. Nadaje się do pomiaru zajętej pamięci, temperatury czy liczby zadań oczekujących w kolejce.
- Histogram — rozkład obserwacji. Pozwala analizować, jak rozkładają się wartości wielu pomiarów, na przykład czasy odpowiedzi. W wariancie klasycznym zapisuje liczności w przedziałach, a także sumę i liczbę obserwacji. Prometheus obsługuje również histogramy natywne, przechowywane w bardziej zwartej postaci.
- Summary — podsumowanie obserwacji. Udostępnia ich liczbę i sumę, a zależnie od konfiguracji także kwantyle obliczane po stronie aplikacji. Takich kwantyli nie można po prostu uśrednić, aby uzyskać poprawny kwantyl dla wielu instancji.
Typ metryki a typ danych w PromQL
Counter czy gauge opisują znaczenie metryki. Typ danych wyrażenia PromQL określa natomiast postać wartości, na której działa zapytanie. To dwa odrębne poziomy: zarówno licznik, jak i gauge mogą być odczytane jako wektor chwilowy.
Wektor chwilowy to zbiór serii, z których każda ma jedną próbkę wybraną dla danego momentu ewaluacji. Wektor zakresowy zawiera dla każdej serii próbki z określonego przedziału czasu. Pierwszy odpowiada potrzebie oceny stanu w danej chwili, drugi dostarcza materiału do analizy zmian w czasie.
PromQL rozróżnia także skalar, czyli pojedynczą liczbę bez etykiet, oraz łańcuch znaków, który ma ograniczone zastosowanie w typowych zapytaniach monitorujących. Próbki w wektorach mogą zawierać liczby zmiennoprzecinkowe, a przy histogramach natywnych — wartości histogramowe.
Warto też oddzielić wektor zakresowy od zapytania wykonywanego dla zakresu czasu. Zapytanie zakresowe oblicza wyrażenie wielokrotnie, w kolejnych krokach czasowych — tak powstają punkty wykresu. Sam wykres nie oznacza więc, że użyte wyrażenie zwraca wektor zakresowy. To rozróżnienie pomaga poprawnie odczytywać wyniki i rozumieć, jakie dane rzeczywiście podlegają analizie.
Selektory i etykiety: matchery, filtrowanie, regex, zakresy czasowe i subquery
Precyzyjne zapytanie w PromQL zaczyna się od wyboru właściwych serii. Sama nazwa metryki zwykle nie wystarcza: pod jedną nazwą mogą znajdować się dane z wielu instancji, przestrzeni nazw czy endpointów. Selektor określa, które serie zostaną uwzględnione, a matchery etykiet pozwalają zawęzić ten wybór do interesującego środowiska, usługi lub zasobu.
Filtrowanie za pomocą etykiet
Etykiety opisują kontekst pomiaru. Zależnie od konfiguracji monitoringu mogą wskazywać między innymi zadanie zbierania danych, instancję, pod, przestrzeń nazw albo kod odpowiedzi HTTP. Przed przygotowaniem filtra warto sprawdzić rzeczywiste etykiety danej metryki — nie każda metryka zawiera ten sam zestaw informacji.
PromQL udostępnia cztery rodzaje matcherów:
- Równość (=) — wybiera serie, których etykieta ma dokładnie wskazaną wartość. To dobry wybór, gdy znasz konkretną instancję lub środowisko.
- Nierówność (!=) — wyklucza serie z określoną wartością etykiety.
- Dopasowanie do wyrażenia regularnego (=~) — pozwala objąć jednym warunkiem kilka wartości albo wartości zgodne z określonym wzorcem.
- Brak dopasowania do wyrażenia regularnego (!~) — odrzuca wartości pasujące do wzorca.
Warunki w jednym selektorze działają łącznie: seria musi spełniać każdy z nich. Filtr środowiska produkcyjnego połączony z filtrem konkretnej przestrzeni nazw wybierze wyłącznie serie spełniające oba wymagania. Dodanie kolejnego matchera zawęża zbiór wynikowy, zamiast tworzyć alternatywną ścieżkę wyboru.
Istotna pułapka dotyczy brakujących etykiet. Matcher pasujący do pustej wartości obejmuje również serie, które nie mają danej etykiety. W efekcie wykluczenie jednej wartości przez nierówność może pozostawić w wynikach także serie pozbawione tej etykiety. Jeśli jej obecność ma znaczenie, trzeba uwzględnić ten warunek w selekcji.
Regex: elastyczny wybór, ale nie dowolne wyszukiwanie
Wyrażenia regularne przydają się, gdy chcesz wybrać rodzinę podobnie nazwanych zasobów lub kilka dopuszczalnych wartości etykiety. W PromQL regex dopasowuje całą wartość etykiety, a nie tylko jej fragment. Samo podanie fragmentu nazwy nie oznacza więc wyszukania wszystkich wartości, które go zawierają — wzorzec musi dopuszczać znaki przed tym fragmentem lub po nim.
Prometheus korzysta ze składni RE2, która nie obsługuje między innymi odwołań wstecznych ani konstrukcji lookaround. Wzorzec sprawdzony w narzędziu używającym innego silnika regex nie musi zatem działać identycznie w PromQL. Gdy potrzebujesz jednej znanej wartości, wybierz zwykłą równość: czytelniej komunikuje intencję i nie wymaga interpretacji wzorca.
Można też wybierać serie bez podawania nazwy metryki. W takim przypadku selektor musi zawierać przynajmniej jeden matcher, który nie pasuje do pustej wartości. W praktyce wskazanie nazwy metryki i konkretnych etykiet pomaga uniknąć przypadkowego objęcia zapytaniem zbyt szerokiego zbioru danych.
Zakres czasowy: okno danych a okres wyświetlania
Selektor chwilowy wybiera dla każdej pasującej serii najnowszą dostępną próbkę w dozwolonym oknie wyszukiwania wstecz, z uwzględnieniem mechanizmu oznaczania serii jako nieaktualnych. Selektor zakresowy pobiera natomiast próbki z określonego przedziału poprzedzającego moment ewaluacji. Lewa granica tego przedziału jest wyłączona, a prawa włączona.
Podczas szkoleń Cognity regularnie wracają pytania o różnicę między oknem danych w zapytaniu a zakresem czasu na wykresie — dlatego wyjaśniamy ją również tutaj. Okno danych w selektorze nie jest tym samym co zakres czasu na wykresie. Wykres obejmujący dobę może wielokrotnie obliczać zapytanie korzystające za każdym razem tylko z ostatnich kilku minut. Okres wyświetlania określa, dla jakich chwil powstaną wyniki, natomiast okno selektora — jakie dane wejściowe będą dostępne przy każdym obliczeniu.
Modyfikator offset przesuwa punkt odniesienia selektora w czasie, co przydaje się przy analizie wcześniejszych danych. Modyfikator @ pozwala powiązać selektor z konkretnym znacznikiem czasu. Żaden z nich nie zmienia zapisanych próbek; wpływają na to, z jakiego momentu zapytanie odczytuje dane.
Subquery: zakres wyników wyrażenia
Selektor zakresowy sięga po zapisane próbki konkretnej metryki. Subquery, czyli podzapytanie, pozwala uzyskać zakres wyników wyrażenia obliczanego wielokrotnie w zadanym przedziale. Jest potrzebne wtedy, gdy dalsza analiza ma dotyczyć przebiegu wartości wyliczonych, a nie bezpośrednio surowych pomiarów.
Podzapytanie ma zakres oraz opcjonalną rozdzielczość, czyli odstęp między kolejnymi obliczeniami wewnętrznego wyrażenia. Nie należy utożsamiać tej rozdzielczości z częstotliwością zbierania metryk. Gęstsze obliczenia nie tworzą nowych pomiarów, a długi zakres połączony z małym krokiem i dużą liczbą serii może istotnie zwiększyć koszt zapytania. Dlatego najpierw warto precyzyjnie ograniczyć wybór danych etykietami, a dopiero potem dobierać zakres i rozdzielczość podzapytania.
Funkcje PromQL w praktyce: rate, irate, increase, funkcje dla liczników i gauge oraz histogram_quantile
Dobór funkcji w PromQL zależy przede wszystkim od tego, co mierzy metryka i na jakie pytanie ma odpowiedzieć zapytanie. Liczbę obsłużonych żądań zwykle warto przeliczyć na tempo ruchu, a bieżące zużycie pamięci — analizować jako poziom, zmianę lub trend. Zapytanie może być poprawne składniowo, a mimo to prowadzić do błędnych wniosków, jeśli funkcja nie pasuje do charakteru danych.
rate, irate i increase — trzy sposoby analizy liczników
Licznik, czyli counter, narasta wraz z kolejnymi zdarzeniami, ale może się wyzerować, na przykład po restarcie procesu. Funkcje rate(), irate() i increase() uwzględniają spadki wartości interpretowane jako resety. Różnią się sposobem obliczania wyniku i jego znaczeniem.
| Funkcja | Co zwraca? | Kiedy jej używać? |
|---|---|---|
rate() | Średni przyrost na sekundę, obliczony na podstawie próbek z wybranego okna. | Do analizy tempa zdarzeń, wykresów trendu i alertów. |
irate() | Przyrost na sekundę wyznaczony z dwóch ostatnich próbek w oknie. | Do obserwowania krótkotrwałych zmian tempa, zwłaszcza na wykresach diagnostycznych. |
increase() | Szacowany przyrost licznika w całym wybranym oknie. | Gdy pytanie dotyczy liczby zdarzeń w danym czasie, a nie ich tempa na sekundę. |
Dla licznika żądań HTTP podstawowe porównanie wygląda następująco:
rate(http_requests_total[5m])
irate(http_requests_total[5m])
increase(http_requests_total[5m])Pierwsze zapytanie pokazuje średnią liczbę żądań na sekundę w ostatnich pięciu minutach. Drugie korzysta tylko z dwóch ostatnich próbek znalezionych w tym przedziale — nie wygładza wyniku na podstawie całych pięciu minut. Trzecie szacuje, o ile wzrósł licznik w tym czasie.
rate() i increase() ekstrapolują wynik do granic okna. Dlatego increase() może zwrócić wartość ułamkową nawet wtedy, gdy licznik rejestruje wyłącznie całkowite liczby zdarzeń. To oszacowanie na podstawie cyklicznych odczytów, nie dokładny rejestr wszystkich żądań.
Do alertów zwykle lepiej nadaje się rate(): wynik oparty na szerszym zestawie próbek jest mniej podatny na chwilowe wahania niż irate(). Okno musi jednak zawierać wystarczającą liczbę odczytów. Przy mniej niż dwóch próbkach funkcje te nie wyznaczą przyrostu dla danej serii.
Funkcje dla gauge — poziom, zmiana i trend
Metryka typu gauge może swobodnie rosnąć i maleć. Dotyczy to na przykład temperatury, długości kolejki czy liczby aktywnych połączeń. Nie należy stosować do niej funkcji przeznaczonych dla liczników: zwykły spadek wartości mógłby zostać potraktowany jako reset.
Do analizy takich danych przydają się trzy różne podejścia:
delta()szacuje różnicę między końcową a początkową wartością w oknie, z ekstrapolacją do jego granic. Odpowiada na pytanie, o ile zmienił się poziom metryki.deriv()wyznacza trend zmian na sekundę za pomocą regresji liniowej. Pomaga ocenić, czy wartość systematycznie rośnie, czy maleje.predict_linear()prognozuje przyszłą wartość na podstawie liniowego trendu próbek. Jest użyteczna przy ocenie, dokąd prowadzi obecna tendencja, ale nie uwzględnia przyszłych skoków obciążenia ani sezonowości.
Jeśli ważniejszy jest poziom niż kierunek zmian, można sięgnąć po avg_over_time(), min_over_time() lub max_over_time(). Funkcje te analizują próbki każdej serii osobno: pozwalają ustalić średnią, minimum lub maksimum w wybranym czasie. Warto pamiętać, że avg_over_time() nadaje każdej próbce taką samą wagę — nie jest to średnia ważona czasem.
Pomocniczo changes() zlicza zmiany wartości między kolejnymi próbkami. Nie należy jej mylić z resets(), która dla liczników służy do wykrywania resetów.
histogram_quantile — oszacowanie percentyla
histogram_quantile() pozwala oszacować kwantyl rozkładu obserwacji, na przykład czas odpowiedzi, poniżej którego mieści się około 95% żądań. Pierwszy argument określa kwantyl: 0.95 oznacza p95. Wynik zachowuje jednostkę obserwacji — dla histogramu czasów zapisanych w sekundach również będzie wyrażony w sekundach.
W przypadku klasycznego histogramu funkcja korzysta z serii koszyków _bucket. Ponieważ zawierają one narastające liczniki obserwacji, do analizy ostatniego okresu zwykle przekazuje się ich tempo przyrostu:
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))Funkcja obsługuje również histogramy natywne, których reprezentacja nie wymaga osobnych serii _bucket. W obu przypadkach percentyl jest oszacowaniem zależnym od rozdzielczości histogramu, a nie wynikiem sortowania pojedynczych pomiarów. Nie można go wiarygodnie wyprowadzić z samej sumy i liczby obserwacji — te wystarczają do obliczenia średniej, lecz nie opisują rozkładu wartości.
Agregacje i grupowanie: sum/avg/max, by/without, agregacje wielowymiarowe
Agregacje w PromQL pozwalają przejść od pojedynczych serii do obrazu całej usługi, klastra lub wybranego środowiska. Zamiast analizować osobno każdą instancję, możesz obliczyć łączną wartość metryki, średnią albo najwyższy wynik w określonej grupie. Kluczowe są dwie decyzje: jak połączyć wartości oraz które etykiety mają wyznaczać granice grup.
Operatory agregujące działają na wektorze chwilowym: łączą wartości różnych serii dla danego momentu ewaluacji. Nie obliczają same z siebie średniej ani maksimum z przedziału czasu. Gdy zapytanie zasila wykres, agregacja jest wykonywana osobno w każdym kroku czasowym.
Sum, avg i max — trzy różne perspektywy
| Operator | Co oblicza w grupie? | Kiedy go wybrać? |
|---|---|---|
sum | Sumę wartości wszystkich serii. | Gdy wartości są addytywne, np. reprezentują ruch obsługiwany przez niezależne instancje. |
avg | Średnią arytmetyczną wartości serii. | Gdy chcesz poznać przeciętny poziom metryki, przypisując każdej serii taką samą wagę. |
max | Największą wartość spośród serii. | Gdy interesuje Cię najbardziej obciążony element, którego wynik mógłby zniknąć w średniej. |
Wybór operatora powinien wynikać ze znaczenia metryki. Suma jest użyteczna tylko wtedy, gdy nie zliczasz wielokrotnie tego samego zjawiska. Jeśli kilka eksporterów raportuje identyczny stan wspólnej kolejki, dodanie ich wskazań zawyży wynik. Z kolei max pokaże najwyższą wartość, ale nie zachowa automatycznie informacji o instancji, z której ona pochodzi — wynik zawiera etykiety wynikające z grupowania. W Cognity omawiamy dobór agregacji zarówno od strony technicznej, jak i praktycznej — zgodnie z realiami pracy uczestników.
By i without — określanie granic agregacji
Bez modyfikatora grupowania operator łączy wszystkie serie wejściowe w jedną grupę. Dla niepustego wejścia typowym wynikiem sum(...) jest więc jedna seria bez etykiet. Modyfikatory by i without pozwalają kontrolować, które wymiary pozostaną widoczne.
bywskazuje etykiety, które mają zostać zachowane. Serie o jednakowych wartościach tych etykiet trafiają do jednej grupy; pozostałe etykiety są pomijane.withoutwskazuje etykiety, które mają zostać usunięte. Wszystkie pozostałe zwykłe etykiety nadal rozróżniają grupy.
Załóżmy, że metryka http_requests_total opisuje żądania obsługiwane przez niezależne instancje i zawiera etykiety cluster, namespace, service oraz instance. Łączne tempo żądań dla każdej usługi w danym klastrze i przestrzeni nazw można przedstawić tak:
sum by (cluster, namespace, service) (
rate(http_requests_total[5m])
)
W tym przykładzie agregacja sumuje tempo żądań obliczone wcześniej dla poszczególnych liczników. Dla liczników najpierw wyznaczaj tempo zmian, a dopiero potem agreguj — pozwala to prawidłowo uwzględnić niezależne restarty instancji.
Przy dokładnie takim zestawie etykiet analogiczne grupowanie zapewni sum without (instance) (...). Różnica pojawi się po dodaniu kolejnej etykiety, np. version: wariant z by nadal połączy wersje, natomiast wariant z without zachowa je jako osobne grupy. Dlatego by jest dobrym wyborem, gdy chcesz jawnie ustalić wymiary wyniku, a without — gdy chcesz usunąć konkretne wymiary techniczne i pozostawić pozostałe.
Agregacje wielowymiarowe i zagnieżdżone
Grupowanie po kilku etykietach tworzy osobny wynik dla każdej ich kombinacji występującej w danych. W powyższym zapytaniu usługi o tej samej nazwie, ale działające w różnych klastrach lub przestrzeniach nazw, pozostają rozdzielone. Usunięcie namespace z listy by połączyłoby ich wyniki w obrębie klastra.
Agregacje można również zagnieżdżać. Poniższe zapytanie najpierw oblicza ruch każdej usługi, a następnie wybiera największą z tych wartości w każdym klastrze:
max by (cluster) (
sum by (cluster, namespace, service) (
rate(http_requests_total[5m])
)
)
Kolejność operacji zmienia znaczenie wyniku: maksimum z sum usług nie jest tym samym co maksimum z wartości pojedynczych instancji. Szczególnej ostrożności wymaga też zagnieżdżanie avg. Średnia ze średnich grup przypisuje każdej grupie jednakową wagę, nawet jeśli grupy mają różną liczbę serii.
Zachowuj tylko te wymiary, które są potrzebne do odpowiedzi na konkretne pytanie. Zbyt szeroka agregacja ukrywa lokalne problemy, a zbyt szczegółowa utrudnia odczyt. Mniejsza liczba serii wynikowych poprawia czytelność wykresu, lecz nie oznacza, że Prometheus nie musi odczytać i przetworzyć wszystkich pasujących serii wejściowych.
Operatory i łączenie serii: arytmetyka, porównania, operatory logiczne i dopasowanie etykiet
Dzielenie dwóch metryk w PromQL nie oznacza automatycznie dzielenia każdej serii z pierwszej metryki przez odpowiadającą jej serię z drugiej. Prometheus musi najpierw ustalić, które serie tworzą pary. Dlatego poprawne wyrażenie może zwrócić pusty wynik, jeśli etykiety po obu stronach operatora nie pasują do siebie.
Operatory binarne działają przede wszystkim na skalarach i wektorach chwilowych. Wektora zakresowego nie można bezpośrednio użyć jako argumentu zwykłego dodawania czy dzielenia — wcześniej trzeba przekształcić go odpowiednią funkcją. Poniższe zasady dotyczą próbek liczbowych; próbki histogramów natywnych mają dodatkowe ograniczenia dotyczące obsługiwanych operatorów.
Operatory arytmetyczne: obliczenia na wartościach próbek
PromQL udostępnia dodawanie +, odejmowanie -, mnożenie *, dzielenie /, resztę z dzielenia % oraz potęgowanie ^. Ich zachowanie zależy od typów argumentów:
- Skalar i skalar: wynikiem jest pojedyncza wartość liczbowa.
- Wektor i skalar: działanie obejmuje każdą próbkę wektora, na przykład mnożenie wszystkich wartości przez
100. - Wektor i wektor: działanie obejmuje wyłącznie dopasowane pary serii. Serie bez odpowiednika nie trafiają do wyniku.
To ostatnie rozróżnienie jest szczególnie ważne: brak dopasowanej serii nie jest traktowany jak zero. Przed wykonaniem obliczenia warto także sprawdzić jednostki. Zgodność etykiet pozwala połączyć dane technicznie, ale nie gwarantuje sensowności otrzymanej wartości.
Porównania: filtrowanie albo wynik 0/1
Operatory ==, !=, >, <, >= i <= domyślnie filtrują serie. Wyrażenie temperature_celsius > 80 pozostawia tylko serie przekraczające próg, zachowując ich rzeczywiste wartości — nie zamienia ich na jedynki.
Dodanie modyfikatora bool zmienia zachowanie: temperature_celsius > bool 80 zwraca 1, gdy warunek jest spełniony, oraz 0, gdy nie jest. Przy porównaniu dwóch wektorów nadal obowiązuje dopasowanie serii. Modyfikator bool nie tworzy zer dla serii bez odpowiednika. W porównaniach dwóch skalarów jego użycie jest wymagane.
Operatory logiczne i zbiorowe: liczy się obecność serii
Operatory and, or oraz unless działają na wektorach chwilowych. Nie interpretują wartości próbek jako prawdy i fałszu — sprawdzają obecność serii o pasujących etykietach.
| Operator | Zachowanie | Zastosowanie |
|---|---|---|
A and B | Zachowuje serie i wartości z A, dla których istnieje dopasowanie w B. | Ograniczanie wyniku do zasobów obecnych w drugim zbiorze. |
A or B | Zwraca serie z A oraz te serie z B, które nie mają dopasowania w A. | Łączenie zbiorów; przy dopasowaniu pierwszeństwo ma lewa strona. |
A unless B | Zachowuje serie z A bez dopasowania w B. | Wykluczanie zasobów wskazanych przez drugi zbiór. |
Seria o wartości 0 nadal istnieje, więc uczestniczy w tych operacjach. Ma to znaczenie przy łączeniu ich z porównaniami: porównanie bez bool usuwa serie niespełniające warunku, natomiast z bool pozostawia je z wartością zero.
on i ignoring: które etykiety decydują o dopasowaniu?
Domyślnie dopasowanie dwóch wektorów wymaga zgodności etykiet i ich wartości, z pominięciem nazwy metryki. Dodatkowa etykieta tylko po jednej stronie może więc uniemożliwić połączenie.
on(instance, job) ogranicza klucz dopasowania do wskazanych etykiet. Z kolei ignoring(status) wyłącza wskazaną etykietę z porównania, pozostawiając pozostałe jako klucz. Te modyfikatory nie agregują danych: pominięcie etykiety nie scala serii, które się nią różnią. Nie należy też traktować ich jako prostego polecenia zachowania lub usunięcia kolumn z wyniku.
group_left i group_right: relacje wiele-do-jednego
Przy arytmetyce i porównaniach domyślne dopasowanie jest jeden-do-jednego. Jeśli dla tego samego klucza po jednej stronie występuje kilka serii, trzeba jawnie określić relację: group_left oznacza wiele serii po lewej stronie, a group_right — wiele po prawej.
Poniższy schemat używa przykładowych metryk: workload_usage opisuje wykorzystanie zasobu przez poszczególne obciążenia, a instance_capacity — pojemność instancji w tej samej jednostce.
workload_usage
/ on(instance) group_left(team)
instance_capacityWiele serii wykorzystania może zostać podzielonych przez jedną wartość pojemności dla danej instancji. group_left(team) dodatkowo przenosi etykietę team ze strony „jeden” do wyniku. Warunek poprawności jest ścisły: prawa strona musi zawierać najwyżej jedną serię dla każdej wartości instance.
Modyfikatory grupowania nie pozwalają na dowolne łączenie wiele-do-wielu. Jeśli klucz nie jest unikalny po stronie „jeden”, należy doprecyzować dopasowanie lub świadomie przygotować dane przez agregację. group_left i group_right stosuje się do arytmetyki i porównań, nie do operatorów zbiorowych. Przy diagnozowaniu problemów najlepiej uruchomić obie strony osobno i sprawdzić etykiety oraz liczbę serii przypadających na wybrany klucz.
Gotowe przykłady zapytań PromQL: CPU, pamięć, dysk, sieć, error rate i uptime
Przy korzystaniu z gotowych zapytań najważniejsze jest dopasowanie ich do źródła metryk. Poniższe przykłady dla hostów wykorzystują Node Exporter, a zapytania dotyczące kontenerów — metryki cAdvisor udostępniane zwykle przez kubelet. Metryka żądań HTTP pochodzi natomiast z instrumentacji aplikacji, dlatego jej nazwę i etykiety trzeba sprawdzić we własnym środowisku.
Przykłady zakładają, że każda seria jest zbierana tylko raz, a etykiety jednoznacznie identyfikują obserwowane zasoby. Jeśli monitorujesz wiele klastrów z powtarzającymi się nazwami podów lub hostów, dodaj filtr klastra albo uwzględnij jego etykietę w grupowaniu. Okno [5m] jest punktem wyjścia: powinno obejmować co najmniej kilka odczytów metryki, a nie być krótsze niż interwał zbierania danych.
CPU: procent wykorzystania hosta i zużycie procesora przez pod
Dla hosta przydatny jest procent czasu, w którym procesory nie pozostawały bezczynne. Poniższe zapytanie zwraca jeden wynik na instance, uśredniony po rdzeniach. Dzięki temu maszyny o różnej liczbie CPU można porównywać na wspólnej skali procentowej.
100 * (1 - avg by (instance) (
rate(node_cpu_seconds_total{mode="idle"}[5m])
))
To miara czasu poza stanem idle, nie wyłącznie czasu wykonywania kodu aplikacji — obejmuje również między innymi iowait. Wysoki wynik warto więc zestawić z charakterem obciążenia, zanim uznasz go za dowód niedoboru mocy obliczeniowej.
W Kubernetes wygodniejszą jednostką są często wykorzystywane rdzenie CPU na pod. Wynik 0.5 oznacza średnie zużycie połowy jednego rdzenia, a 2 — dwóch rdzeni. Nie jest to procent limitu CPU poda.
sum by (namespace, pod) (
rate(container_cpu_usage_seconds_total{
namespace!="", pod!="", container!="", container!="POD"
}[5m])
)
Grupowanie po namespace, pod pomaga znaleźć konkretny obciążony pod. Jeśli potrzebujesz zestawienia zużycia całych przestrzeni nazw, pozostaw w tym zapytaniu tylko by (namespace).
Pamięć: wykorzystanie RAM hosta i working set kontenerów
Na hoście z Linuksem oceniaj zajętość pamięci z użyciem MemAvailable, a nie wyłącznie MemFree. Pierwsza z tych wartości uwzględnia szacowaną pamięć dostępną dla aplikacji, w tym część możliwą do odzyskania z cache. Zapytanie zwraca procent wykorzystania RAM dla każdej instancji.
100 * (
1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes
)
Dla podów można obserwować sumę working set kontenerów, tutaj przeliczoną na GiB. Jest to użyteczny wskaźnik roboczego zużycia pamięci, ale nie dokładna miara pamięci niemożliwej do odzyskania ani procent wykorzystania limitu.
sum by (namespace, pod) (
container_memory_working_set_bytes{
namespace!="", pod!="", container!="", container!="POD"
}
) / 1024 / 1024 / 1024
Takie zestawienie pomaga wskazać pody odpowiedzialne za wzrost zużycia RAM. Ocena ryzyka zakończenia kontenera z powodu przekroczenia limitu pamięci wymaga dodatkowo porównania wyniku z jego limitem oraz sprawdzenia zdarzeń OOM.
Dysk: zajętość systemu plików zamiast ogólnej średniej
Pojemność dysku monitoruj osobno dla punktów montowania. Średnia dla całego hosta może ukryć sytuację, w której partycja z danymi jest niemal pełna, a pozostałe mają duży zapas. Poniższe zapytanie pokazuje procent pojemności niedostępnej dla zwykłego użytkownika, zachowując między innymi etykiety instance, device i mountpoint.
100 * (
1 -
node_filesystem_avail_bytes{fstype!~"tmpfs|devtmpfs|overlay"}
/
node_filesystem_size_bytes{fstype!~"tmpfs|devtmpfs|overlay"}
)
Lista wykluczonych systemów plików jest przykładowa — dopasuj ją do hostów i monitorowanych wolumenów. Użycie avail uwzględnia ograniczenia dostępności miejsca, w tym bloki zarezerwowane. Ten wynik opisuje pojemność, nie wydajność I/O; nie wyjaśni samodzielnie opóźnień zapisu ani odczytu.
Sieć: odbierany i wysyłany ruch na interfejs
Ruch sieciowy najlepiej początkowo rozdzielić według instancji i interfejsu. Pozwala to uniknąć mylącego sumowania tych samych pakietów obserwowanych na interfejsach fizycznych, mostach i interfejsach wirtualnych. Pierwsze zapytanie zwraca ruch przychodzący, drugie — wychodzący, w bitach na sekundę.
8 * rate(node_network_receive_bytes_total{device!="lo"}[5m])
8 * rate(node_network_transmit_bytes_total{device!="lo"}[5m])
Na wykresie użyj legendy zawierającej instance i device. Wykluczenie interfejsu zwrotnego lo to tylko pierwszy filtr; do oceny wykorzystania łącza wybierz właściwe interfejsy fizyczne lub logiczne. Sam transfer nie mówi jeszcze o utracie pakietów ani błędach transmisji.
Error rate: udział odpowiedzi 5xx w ruchu aplikacji
Odsetek błędów pokazuje skalę problemu względem obsługiwanego ruchu. Poniższy przykład zakłada istnienie licznika http_requests_total z etykietami status i job. Wynikiem jest procent odpowiedzi 5xx dla każdego zadania zbierania metryk.
100 *
sum by (job) (
rate(http_requests_total{status=~"5.."}[5m])
)
/
sum by (job) (
rate(http_requests_total[5m])
)
Najpierw sumowane są błędy i żądania, a dopiero potem obliczany jest procent. Dzięki temu instancja obsługująca niewielki ruch nie ma takiego samego wpływu na wynik jak instancja obsługująca większość żądań. Etykieta job nie zawsze oznacza pojedynczą usługę — w razie potrzeby zastąp ją właściwą etykietą aplikacji po obu stronach dzielenia.
Przy zerowym ruchu wynik może być NaN, a jeśli seria dla odpowiedzi 5xx nie istnieje, zapytanie może nie zwrócić wyniku dla danej grupy. Nie traktuj automatycznie braku danych jako zerowego poziomu błędów. Obok procentu warto wyświetlać również liczbę żądań na sekundę.
Uptime: czas od uruchomienia a dostępność monitoringu
Czas od uruchomienia hosta, wyrażony w godzinach, można obliczyć na podstawie metryk zegara i startu systemu:
(node_time_seconds - node_boot_time_seconds) / 3600
Spadek tej wartości zwykle wskazuje restart hosta. Nie jest to jednak pomiar dostępności aplikacji. Z kolei metryka up informuje, czy Prometheus zdołał poprawnie pobrać metryki z danego celu: 1 oznacza udany scrape, a 0 — nieudany.
100 * avg_over_time(up[24h])
Ostatnie zapytanie pokazuje procent udanych odczytów wśród zapisanych próbek z ostatnich 24 godzin, osobno dla każdego celu. To wskaźnik osiągalności endpointu metryk, nie pełny uptime usługi ani realizacja SLA. Przerwy w działaniu samego Prometheusa i usunięcie celu z konfiguracji nie muszą pojawić się jako zera, dlatego wynik wymaga interpretacji razem z kompletnością danych.
Latencje i percentyle z histogramów: budowa zapytań, typowe wzorce i walidacja wyników
Średni czas odpowiedzi może wyglądać dobrze nawet wtedy, gdy część użytkowników doświadcza wyraźnych opóźnień. Dlatego do analizy latencji warto wykorzystać percentyle: p50 opisuje medianę, p95 wskazuje czas, w którym mieści się około 95% obserwacji, a p99 pozwala śledzić najwolniejszy fragment ruchu. W Prometheusie percentyle wyznaczane z histogramów są oszacowaniem na podstawie rozkładu obserwacji w przedziałach, a nie dokładnym wynikiem obliczonym z zapisanych czasów wszystkich żądań.
Jak zbudować obliczenie percentyla
W klasycznym histogramie każdy bucket zlicza obserwacje nieprzekraczające jego górnej granicy, zapisanej w etykiecie le. Buckety są kumulacyjne: żądanie trwające 100 ms trafia również do wszystkich przedziałów o wyższej granicy. Histogram natywny przechowuje rozkład w próbkach histogramowych, zamiast udostępniać osobną serię dla każdego przedziału. Oba warianty pozwalają analizować percentyle, ale wymagają innego sposobu agregowania danych wejściowych.
Budowę zapytania dla typowego histogramu czasów żądań należy rozpocząć od wyboru zakresu obserwacji: usługi, rodzaju operacji i okna czasowego. Następnie funkcja rate przekształca narastające liczniki histogramu w tempo przyrostu obserwacji. Dopiero później agreguje się dane z wybranych instancji i przekazuje wynik do histogram_quantile, wskazując oczekiwany percentyl.
W przypadku klasycznych histogramów agregacja musi zachować etykietę le oraz etykiety identyfikujące analizowane grupy, na przykład usługę lub trasę HTTP. Histogramy natywne nie wymagają zachowania le. Tempo przyrostu należy obliczyć przed agregacją, aby restarty poszczególnych instancji i związane z nimi wyzerowania liczników mogły zostać poprawnie uwzględnione.
Typowe wzorce analizy latencji
Percentyl dla całej usługi oblicza się z połączonego rozkładu żądań obsłużonych przez jej instancje. Nie należy uśredniać percentyli wyliczonych osobno dla poszczególnych instancji. Średnia z kilku wartości p95 nie jest p95 całego ruchu, również wtedy, gdy instancje obsłużyły podobną liczbę żądań.
Do diagnozowania problemów przydaje się rozbicie percentyli według tras lub typów operacji. Jeden wynik obejmujący szybkie odczyty i długotrwałe operacje raportowe może ukrywać źródło pogorszenia wydajności. Z kolei porównanie percentyla całej usługi z wynikami poszczególnych instancji pomaga zauważyć nierównomierne obciążenie albo lokalne spowolnienie.
Jeżeli wymaganie brzmi „95% żądań ma kończyć się w czasie poniżej ustalonego progu”, warto również mierzyć udział obserwacji mieszczących się w tym limicie. W klasycznym histogramie, gdy próg odpowiada granicy bucketu, taki udział można wyznaczyć bez interpolowania percentyla. Średnia latencja, uzyskana z przyrostu sumy czasów i liczby obserwacji w tym samym oknie, pozostaje użytecznym uzupełnieniem, ale nie zastępuje analizy ogona rozkładu.
Jak sprawdzić wiarygodność wyniku
- Zweryfikuj jednostkę i granice przedziałów. Jeśli histogram rejestruje sekundy, wynik percentyla również jest wyrażony w sekundach. Szerokie buckety w pobliżu interesującego progu oznaczają większą niepewność oszacowania.
- Sprawdź liczbę obserwacji. Przy niewielkim ruchu, szczególnie dla p99, pojedyncze żądania mogą mocno zmieniać wynik. Dłuższe okno zwiększa liczbę próbek, ale może wygładzać krótkie incydenty.
- Oceń kompletność histogramu. Klasyczny histogram powinien zawierać bucket z granicą +Inf, obejmujący wszystkie obserwacje. Jeśli szukany percentyl wpada do tego przedziału, funkcja zwraca najwyższą skończoną granicę, a nie rzeczywistą latencję z tego obszaru.
- Kontroluj zgodność agregowanych danych. Klasyczne histogramy łączone w jeden rozkład powinny mieć takie same granice bucketów. Wszystkie dane muszą też dotyczyć tej samej jednostki i porównywalnych zdarzeń.
- Odróżniaj brak wyniku od dobrej wydajności. Brak obserwacji może prowadzić do wartości NaN, a brak serii — do pustego wyniku. Żaden z tych przypadków nie oznacza zerowej latencji.
Wzrost percentyla warto zestawić z natężeniem ruchu, liczbą błędów i zmianami wdrożeniowymi. Pozwala to odróżnić rzeczywiste spowolnienie od zmiany struktury żądań lub niedoskonałości pomiaru — zanim wynik stanie się podstawą alertu albo oceny spełnienia SLO.
Typowe pułapki i debugowanie: rate vs irate, kardynalność etykiet, brakujące dane, Prometheus UI i Grafana
Poprawne składniowo zapytanie PromQL nie musi dawać wiarygodnego obrazu systemu. Płaski wykres może wynikać ze zbyt szerokiego okna obliczeń, luka — z przerwanego zbierania metryk, a nagły wzrost liczby serii — z dodania jednej etykiety. Debugowanie warto więc zaczynać nie od przebudowy zapytania, lecz od sprawdzenia danych wejściowych, czasu ich pobrania i ustawień wizualizacji.
Rate i irate: stabilny trend czy chwilowa zmiana?
Obie funkcje służą do obliczania tempa przyrostu licznika, ale odpowiadają na nieco inne pytania. Rate wykorzystuje próbki z całego wskazanego okna, dlatego lepiej nadaje się do obserwowania trendów i zwykle jest właściwym wyborem w regułach alertowych. Irate opiera wynik na dwóch ostatnich próbkach: pokazuje krótkotrwałe zmiany, lecz jest bardziej podatne na wahania. Poszerzenie okna dla irate nie wygładza wyniku tak jak w przypadku rate.
Typową pułapką jest zbyt krótkie okno względem interwału zbierania metryk. Do obliczenia tempa potrzebne są co najmniej dwie próbki, a opóźniony lub pominięty odczyt może sprawić, że ich zabraknie. Praktycznym punktem wyjścia dla rate jest okno obejmujące co najmniej cztery interwały zbierania. W Grafanie zmienna $__rate_interval pomaga dobrać je automatycznie, pod warunkiem prawidłowego skonfigurowania interwału odczytu w źródle danych lub odpowiedniego ustawienia Min step.
Ważna jest również kolejność działań: tempo należy obliczać dla poszczególnych liczników, a dopiero potem agregować wyniki. Wcześniejsze zsumowanie liczników może utrudnić prawidłowe rozpoznanie resetu jednej z instancji. Rate ani irate nie należy używać do metryk typu gauge, które mogą naturalnie rosnąć i maleć.
Kardynalność: koszt ukryty w etykietach
Każda unikalna kombinacja wartości etykiet tworzy osobną serię czasową. Etykiety zawierające identyfikator żądania, identyfikator użytkownika lub pełny adres URL z parametrami mogą więc gwałtownie zwiększyć liczbę serii. Skutkiem bywają większe zużycie pamięci, wolniejsze zapytania i rosnące koszty przechowywania danych.
Gdy problem pojawia się po wdrożeniu, sprawdź w Prometheusie statystyki TSDB oraz metryki i etykiety odpowiadające za największą liczbę serii. Agregacja w zapytaniu zmniejsza liczbę wyników, ale nie usuwa kosztu przechowywania danych źródłowych. Trwałe rozwiązanie zwykle wymaga poprawienia instrumentacji, na przykład zastąpienia konkretnych adresów ścieżek wzorcami tras.
Brak danych nie oznacza zera
Pusta odpowiedź może oznaczać niedopasowane etykiety, niedostępny endpoint metryk, wycofaną instancję albo zbyt małą liczbę próbek w oknie. Nie jest równoznaczna z zerową liczbą błędów czy zerowym obciążeniem. Automatyczne zastępowanie braków zerami potrafi ukryć awarię monitoringu.
Najpierw sprawdź stan celu zbierania w widoku Targets oraz metrykę up. Wartość zero wskazuje nieudane pobranie danych z danego celu; brak samej serii up wymaga również sprawdzenia konfiguracji i wykrywania celów. Następnie zweryfikuj, czy oczekiwana metryka rzeczywiście jest eksportowana. Poprawne pobranie endpointu nie gwarantuje obecności każdej metryki aplikacyjnej.
Prometheus UI i Grafana: porównuj te same warunki
Prometheus UI pomaga odizolować problem zapytania od konfiguracji panelu. Grafana dodaje natomiast zmienne, transformacje i ustawienia prezentacji, które mogą zmienić widoczny wynik. Przy rozbieżnościach sprawdź kolejno:
- Dane źródłowe: uruchom w Prometheus UI prosty wybór problematycznej metryki i sprawdź jej etykiety oraz próbki.
- Warunki wykonania: porównaj źródło danych, zakres czasu, moment ewaluacji i tryb zapytania — chwilowy lub zakresowy.
- Rozdzielczość: zweryfikuj krok zapytania. Większy krok może pominąć krótkie skoki, ponieważ zapytanie jest oceniane rzadziej.
- Konfigurację panelu: w Query Inspector sprawdź faktycznie wysłane zapytanie i odpowiedź. Następnie przejrzyj podstawione zmienne, transformacje, jednostki oraz sposób wyświetlania luk.
Najskuteczniejsza metoda to uproszczenie zapytania do surowej metryki, a następnie przywracanie kolejnych operacji pojedynczo. Pozwala ustalić, czy problem leży w zbieraniu danych, obliczeniach PromQL, czy dopiero w ich prezentacji. W Cognity łączymy teorię z praktyką — dlatego zagadnienia analizy metryk i debugowania zapytań rozwijamy także w formie ćwiczeń na szkoleniach.
Najczęściej zadawane pytania i odpowiedzi odnośnie PromQL w praktyce – jak analizować metryki Prometheusa i tworzyć zaawansowane zapytania?
rate() służy do analizy średniego tempa zdarzeń, irate() do obserwowania krótkotrwałych zmian, a increase() do szacowania liczby zdarzeń w wybranym okresie. Wszystkie trzy funkcje stosuje się do liczników, z uwzględnieniem ich resetów. Do alertów zwykle najlepiej nadaje się rate(). Funkcja irate() wykorzystuje tylko dwie ostatnie próbki, natomiast increase() może zwracać wartości ułamkowe, ponieważ ekstrapoluje przyrost do granic okna.
Praktycznym punktem wyjścia dla rate() jest okno obejmujące co najmniej cztery interwały zbierania metryk. Zbyt krótkie okno zwiększa ryzyko braku wyniku po pominiętym lub opóźnionym odczycie, a zbyt długie może wygładzać krótkie incydenty. W Grafanie pomocna jest zmienna $__rate_interval, jeśli interwał zbierania został poprawnie skonfigurowany. Okno obliczeń nie jest tym samym co okres wyświetlany na wykresie.
Pusty wynik może wynikać z filtrów etykiet, niedopasowania serii po obu stronach operatora albo zbyt małej liczby próbek w oknie. Obecność metryki nie gwarantuje, że bardziej złożone wyrażenie znajdzie odpowiednie dane.
- Uruchom samą nazwę metryki i sprawdź dostępne etykiety.
- Dodawaj filtry oraz funkcje pojedynczo, obserwując wynik.
- Przy dzieleniu uruchom obie strony osobno i porównaj ich etykiety.
Nie zastępuj automatycznie braków zerami, ponieważ możesz ukryć problem monitoringu.
P95 całej usługi należy obliczyć z połączonego rozkładu obserwacji, a nie ze średniej percentyli poszczególnych instancji. Dla klasycznego histogramu najpierw zastosuj rate() do serii _bucket, następnie zsumuj wyniki, zachowując etykietę le oraz etykiety identyfikujące usługę. Tak przygotowane dane przekaż do histogram_quantile() z argumentem 0.95. Wynik pozostaje oszacowaniem, którego dokładność zależy od granic bucketów i liczby obserwacji.
by zachowuje tylko wskazane etykiety grupowania, natomiast without usuwa wskazane etykiety i pozostawia pozostałe zwykłe etykiety. Różnica staje się istotna po dodaniu nowego wymiaru, na przykład wersji aplikacji. Zapytanie z by nadal połączy wersje, jeśli nie wskazano tej etykiety, a wariant z without może rozdzielić je na osobne grupy. Wybierz by, gdy chcesz jawnie określić strukturę wyniku.
Błąd many-to-many matching wymaga doprecyzowania klucza dopasowania lub świadomej agregacji danych, aby jedna strona miała unikalną serię dla każdego klucza. Uruchom obie części wyrażenia osobno i sprawdź, które etykiety odróżniają powtarzające się serie. Modyfikatory group_left i group_right obsługują relacje wiele-do-jednego, ale nie usuwają problemu duplikatów po stronie „jeden”. Samo użycie on() lub ignoring() również nie scala serii.
Koszt zapytania PromQL można ograniczyć przez precyzyjny wybór serii oraz rozsądny dobór zakresu i rozdzielczości podzapytań. Zacznij od filtrów wskazujących konkretną usługę, środowisko lub zasób, zamiast przetwarzać wszystkie dostępne dane. Długie podzapytanie z małym krokiem może wymagać wielu obliczeń. Sama agregacja zmniejsza liczbę wyników, ale nie eliminuje kosztu odczytu serii źródłowych. Nadmierna kardynalność etykiet wymaga poprawy instrumentacji.
Rozbieżności między Grafaną a interfejsem Prometheusa mogą wynikać z różnych warunków wykonania zapytania lub ustawień prezentacji danych. Najpierw skopiuj z Query Inspector wyrażenie po podstawieniu zmiennych i porównaj wyniki dla tego samego momentu.
- Sprawdź źródło danych, zakres czasu i tryb zapytania.
- Porównaj krok obliczeń oraz użyte okno danych.
- Zweryfikuj transformacje panelu, jednostki i sposób wyświetlania luk.
Jeśli wyniki obliczeń są zgodne, popraw konfigurację panelu zamiast zmieniać PromQL.