Tutoriale how-to
jq w Zabbixie: JSONPath, JavaScript i kiedy użyć CLI
Zaktualizowano: Autor: Andrzej Niemiec7 min czytania
Zabbix nie ma wbudowanego jq. Jak działają kroki wstępne JSONPath i JavaScript, jakie mają limity i kiedy użyć jq z CLI oraz JSONata.
Spis treści
Czy Zabbix ma wbudowane jq?
Nie. Dokumentacja Zabbix wymienia wśród kroków wstępnych między innymi JSONPath i JavaScript, a nie jq [1]. jq jest osobnym procesorem JSON uruchamianym z wiersza poleceń, opisanym we własnym podręczniku [2]. Mylenie warstw bierze się stąd, że w polskiej serii „Zabbix + Grafana” parsery JSONata i jq omawiane są w osobnych częściach, obok parsera UQL [3]. To narzędzia towarzyszące integracji, a nie elementy serwera monitoringu.
Podział jest praktyczny. Selekcję i proste agregacje wykonuje się w Zabbixie, a złożone transformacje poza nim: w powłoce, skrypcie wdrożeniowym albo potoku CI. Decyzja zależy od tego, czy dane mają trafić do pozycji Zabbix, czy tylko do raportu lub dashboardu.
Czy JSONata jest mechanizmem Zabbix?
Nie ma na to potwierdzenia w dokumentacji. Lista kroków wstępnych Zabbix nie zawiera JSONata [1]. JSONata to odrębny język zapytań z własną specyfikacją, w której istotne są reguły sekwencji i spłaszczania tablic [4]. Pojawia się po stronie warstwy integracji, gdzie trzeba ułożyć odpowiedź API w kształt oczekiwany przez narzędzie wizualizacyjne [3].
W samym Zabbixie tę rolę pełni JSONPath [5]. Jego zakres jest węższy niż JSONata i jq: obejmuje ścieżki, wildcardy, indeksy tablic, filtry warunkowe, wyszukiwanie rekursywne typu $..pole oraz funkcje agregujące sum, avg, min, max, length i first [5]. Ten zestaw wystarcza do selekcji i prostych obliczeń, ale nie do wieloetapowych transformacji.
Co potrafi JSONPath w Zabbixie?
JSONPath wybiera fragmenty JSON bez pisania kodu: obsługuje ścieżki, wildcardy, indeksy tablic, filtry i funkcje agregujące [5]. Wynik zależy od tego, czy ścieżka jest określona, czy nie — dla ścieżki nieokreślonej Zabbix zwraca tablicę trafień, a nie pojedynczą wartość [5].
W praktyce oznacza to, że jedną pozycję HTTP Agent można oprzeć na odpowiedzi API i wyciągnąć z niej konkretne pole przez indeks tablicy. Gdy potrzebna jest suma lub średnia z wielu elementów, dokumentacja wskazuje funkcje sum, avg, min, max, length i first [5]. Dla danych zagnieżdżonych dostępne jest wyszukiwanie rekursywne, więc pole o znanej nazwie można znaleźć niezależnie od głębokości — o ile nie występuje w wielu miejscach, bo wtedy trafień będzie kilka [5].
Ograniczenie jest jedno i ważne: JSONPath nie wykonuje obliczeń zależnych od wielu pól ani nie buduje nowych struktur. Jeśli wynik ma być obiektem z kilkoma polami, potrzebny jest krok JavaScript.
Jakie limity ma preprocessing JavaScript?
JavaScript w Zabbixie przetwarza wartość dowolnym kodem w silniku Duktape, z limitem 10 sekund na wykonanie i 512 MB sterty [6]. Wartość wejściowa trafia do zmiennej value, a wynik zwraca się jako tekst.
Przykład: odpowiedź API z listą serwerów można sparsować i policzyć średnie zużycie procesora. Kod ma postać var d = JSON.parse(value); var s = d.servers; var sum = 0; for (var i = 0; i < s.length; i++) { sum += s[i].cpu; } return (sum / s.length).toFixed(2); — wynik jest liczbą gotową do zapisania w pozycji [6]. Ten sam mechanizm obsługuje łączenie pól, filtrowanie i budowanie nowego obiektu zwracanego przez JSON.stringify [6].
Limity trzeba traktować poważnie. 10 sekund to czas na całe przetworzenie, a 512 MB to sufit pamięci jednego wywołania [6]. Przy dużych odpowiedziach API lepiej ograniczyć payload po stronie źródła, przez parametry zapytania, niż liczyć na to, że skrypt zdąży.
jq czy preprocessing Zabbix — co wybrać?
Wybór zależy od miejsca, w którym dane mają być użyte. jq działa poza Zabbixem, w powłoce i skryptach. Preprocessing działa wewnątrz pozycji i obejmuje JSONPath oraz JavaScript [1].
| Kryterium | jq | JSONPath w Zabbixie | JavaScript w Zabbixie |
|---|---|---|---|
| Gdzie działa | powłoka, skrypty, CI | krok wstępny pozycji | krok wstępny pozycji |
| Selekcja i filtry | pełny język zapytań [2] | ścieżki, wildcardy, filtry [5] | dowolny kod [6] |
| Agregacje | add, length, własne wyrażenia [2] | sum, avg, min, max [5] | pętle i funkcje [6] |
| Limit wykonania | brak wbudowanego | limit czasu kroku wstępnego | 10 s i 512 MB [6] |
| Utrzymanie | skrypt do wersjonowania | konfiguracja w interfejsie | kod w konfiguracji pozycji |
Tabela pokazuje podział pracy. Wszystko, co ma dziać się w czasie rzeczywistym i zasilić trigger, powinno zostać w Zabbixie. Wszystko, co jest raportem, migawką albo jednorazowym przetworzeniem, wygodniej zrobić w jq.
Jak używać jq z API Zabbix?
jq czyta JSON ze standardowego wejścia i wypisuje wynik transformacji [2]. Oficjalny blog Zabbix pokazuje wzorzec, w którym curl wysyła zapytanie do API, a jq wybiera z odpowiedzi potrzebne pola, także przez jq -r do wyciągnięcia wartości tekstowej [7].
Przykład z tego materiału: odpowiedź API zawiera tablicę result, a jq -r '.result[].host' daje listę nazw — po jednej w wierszu, gotową do dalszego przetwarzania w powłoce [7]. Podręcznik jq opisuje operatory selekcji, iteracji i konstruktory obiektów, więc ten sam mechanizm obsługuje filtrowanie po wartościach i budowanie własnych struktur [2]. Strona podręcznika systemowego Ubuntu podaje dodatkowo, że jq czyta kolejne dokumenty JSON ze strumienia, co przydaje się przy logach [10].
Warto rozdzielić role. jq nie jest krokiem wstępnym Zabbix i nie zostanie uruchomiony przez serwer monitoringu [1]. To narzędzie administratora albo zadania harmonogramu, które pobiera dane z API i zapisuje je dalej. Ten sam wzorzec sprawdza się przy wdrażaniu narzędzi w produkcji, o czym piszemy w tekście o praktycznych zastosowaniach AI.
Jak sprawdzić wyrażenie JSON przed wdrożeniem?
Najpierw na kopii danych. Dla JSONPath test odbywa się w interfejsie Zabbix: krok wstępny ma podgląd wyniku, więc widać, czy ścieżka zwraca jedną wartość, czy tablicę [5]. Dla JavaScriptu to samo dotyczy wartości zwracanej przez skrypt — błąd składni albo przekroczenie limitu 10 sekund kończy przetwarzanie i trafia do logu serwera [6].
Dla jq najszybsza jest konsola: ten sam payload można przepuścić przez wyrażenie i porównać wynik z oczekiwaniem [2]. Zasada jest wspólna — testować na danych brzegowych: pustej tablicy, brakującym polu i wartości tekstowej tam, gdzie spodziewana jest liczba [6]. Większość błędów w preprocessingu ujawnia się na takich rekordach, a nie na typowej odpowiedzi API.
Wersje mają znaczenie. 1 października 2026 r. Zabbix opublikował wydanie 8.0.0rc1, a informacja o wersji 8.0 LTS wskazuje planowaną premierę w czwartym kwartale 2026 r. [8][9]. Dokumentacja 8.0 jest osobną gałęzią, więc przed wdrożeniem warto sprawdzić, którą się czyta [9].
Kiedy JSONata ma sens?
JSONata to samodzielny język zapytań, a nie mechanizm Zabbix [1][4]. Ma własne reguły sekwencji i spłaszczania tablic, które trzeba znać, bo wynik bywa inny, niż sugeruje kształt wejścia [4][11]. W polskiej serii o integracji Zabbix + Grafana JSONata i jq są omówione w osobnych częściach, obok parsera UQL — jako narzędzia warstwy integracyjnej [3][11].
JSONata sprawdza się tam, gdzie dane trzeba ułożyć w jeden dokument na potrzeby dashboardu i gdzie logika jest rozbudowana [4]. W samym Zabbixie jej rolę przejmują JSONPath i JavaScript [5][6]. Jeśli zespół zna jq, prostsze zadania szybciej zamknie w powłoce niż w kolejnym języku zapytań.
Decyzja jest więc organizacyjna: jeden język mniej to mniej miejsc, w których trzeba sprawdzać składnię. Narzędzia wiersza poleceń mają też swoją cenę — o pułapkach automatyzacji pisaliśmy w tekście o Codexie w data science.
Najczęstsze pytania
Czy Zabbix obsługuje jq jako krok wstępny?
Nie. Lista kroków wstępnych obejmuje między innymi JSONPath i JavaScript, a jq nie występuje na niej [1]. jq jest osobnym procesorem wiersza poleceń [2]. Można go użyć obok Zabbixa — w skrypcie, który pobiera dane z API — ale serwer monitoringu nie uruchomi go sam.
Czym różni się JSONPath od JSONata?
JSONPath to mechanizm preprocessingu wbudowany w Zabbix: ścieżki, wildcardy, filtry i funkcje agregujące [5]. JSONata to odrębny język zapytań z własną specyfikacją i regułami sekwencji [4]. W Zabbixie nie ma kroku JSONata, więc wybór dotyczy narzędzia poza serwerem, a nie konfiguracji pozycji [1].
Ile trwa preprocessing JavaScript i jakie ma limity?
Jedno wywołanie ma limit 10 sekund na wykonanie i 512 MB sterty, a silnikiem jest Duktape [6]. Wartość wejściowa trafia do zmiennej value, wynik zwraca się jako tekst [6]. Przekroczenie limitu kończy przetwarzanie, dlatego duże odpowiedzi API warto ograniczać już na poziomie zapytania.
Czy jq zastąpi preprocessing w Zabbixie?
Nie. jq działa poza serwerem monitoringu [2]. Zastępuje preprocessing tylko wtedy, gdy dane nie muszą trafić do pozycji Zabbix, na przykład w raportach i migawkach [7]. Do triggerów i alertów potrzebny jest krok wstępny: JSONPath albo JavaScript [1].
Od której wersji Zabbix ma JSONPath?
Dokumentacja bieżącej gałęzi opisuje JSONPath jako dostępny mechanizm, a wydanie 8.0.0rc1 ukazało się 1 października 2026 r. [8][1]. Przy starszych instalacjach trzeba sprawdzić dokumentację odpowiadającą własnej wersji, bo gałęzie opisują różne stany produktu [9].
Źródła
- Item value preprocessing (Zabbix documentation, 2026)
- jq 1.8 Manual (jqlang, 2025)
- Zabbix + Grafana – część 8 – Parser JQ (Sekurak, 2024)
- JSONata Documentation (JSONata, 2025)
- JSONPath functionality (Zabbix documentation, 2026)
- JavaScript preprocessing (Zabbix documentation, 2026)
- Zabbix API scripting via curl and jq (Zabbix Blog, 2023)
- Release Notes for Zabbix 8.0.0rc1 (Zabbix, 2026)
- Zabbix Life Cycle and Release Policy (Zabbix, 2026)
- Ubuntu Manpage: jq – Command-line JSON processor (Ubuntu, 2022)
- Simple Queries (JSONata documentation, 2025)
Fanatyk nowych technologii i specjalista w zakresie sztucznej inteligencji.
Jak powstają teksty: Polityka AI · O redakcji