Metryki Prometheus

OxPHP udostępnia metryki zgodne z Prometheus w tekstowym formacie ekspozycji pod GET /metrics na serwerze wewnętrznym. Obejmują one przepustowość żądań, czasy odpowiedzi, stan połączeń, kondycję puli workerów, buforowanie plików statycznych, wydajność kompresji oraz wydajność trybu worker.

Włączanie metryk

Ustaw INTERNAL_ADDR, aby uruchomić serwer wewnętrzny:

Następnie zbieraj dane z Prometheusa lub dowolnego kompatybilnego kolektora:

Metryki serwera

Metryki żądań

Histogram czasu trwania żądania

Granice przedziałów (mikrosekundy): 100, 500, 1000, 2500, 5000, 10000, 25000, 50000, 100000, 250000, 500000, 1000000, +Inf.

Użyj tego histogramu, aby śledzić ogólne opóźnienia, identyfikować wolne endpointy i mierzyć percentyle opóźnień ogona.

Metryki połączeń

Odczytywanie głębokości kolejki względem slotów przyjęcia

Te dwa wskaźniki odpowiadają na różne połowy jednego pytania: czy cokolwiek się rusza, a nie jak głęboka jest kolejka. oxphp_queue_depth mówi, co czeka; oxphp_admission_slots_available mówi, czy można wpuścić coś więcej. Odczytuj oba względem oxphp_busy_workers.

Trzy ostatnie wiersze to postaci, jakie przybiera wstrzymana pula. W każdej z nich reszta obrazu wygląda zdrowo, choć żadne żądanie PHP się nie kończy: żaden worker nie jest zajęty, liveness przez cały czas odpowiada 200, a readiness przez pierwszą minutę, pliki statyczne są serwowane normalnie. Liczniki odmów rosną, ale rosną też przy zwykłym przeciążeniu. oxphp_pending_requests rośnie wraz z zablokowaną kolejką, a potem spada, gdy każde przybywające żądanie dostaje odpowiedź po upływie własnego budżetu, więc samo w sobie nic tu nie znaczy; odczytane względem oxphp_queue_depth — już tak: pending bliskie zera przy głębokości na poziomie pojemności to zaklinowanie trzymające wszystko, co kiedykolwiek dostało.

Serwer również zauważa zaklinowanie. Ilekroć dwa kolejne jednosekundowe skany widzą czekającą pracę (żądania w kolejce albo rosnące odmowy), przy co najmniej jednym bezczynnym workerze i puli, która niczego nie zakończyła, loguje:

Komunikat powtarza się mniej więcej raz na minutę, dopóki stan trwa, a gdy praca ruszy, pojawia się INFO PHP pool is reaching workers again. Pola leżą pod fields, więc reguła alertu potrzebuje .fields.queue_depth, a nie .queue_depth. Trzy zabezpieczenia zapobiegają fałszywym zgłoszeniom: dwa skany zamiast jednego; postęp mierzony tym, co workery zakończyły, a nie tym, co otrzymali klienci, więc burza przerwań po stronie klientów wygląda jak zajęta pula, którą w istocie jest; oraz brak zgłoszeń, dopóki pula nie zakończy pierwszego żądania, więc bootstrap przy starcie nie jest mylony z zaklinowaniem.

To ostatnie zabezpieczenie obejmuje tylko pierwszy bootstrap procesu. Worker poddany recyklingowi później (z powodu pułapu pamięci albo Worker::scheduleExit()) ponownie uruchamia swoją aplikację i do podjęcia pierwszego żądania wygląda na bezczynny, więc powolny bootstrap w puli z jednym workerem (albo w większej puli, której pozostałe workery są wszystkie zajęte) daje jedno fałszywe ostrzeżenie, a po nim komunikat o powrocie do normy. Rozpoznasz go po oxphp_workers_spawned_total rosnącym w tym samym momencie.

Ostrzeżenie jest emitowane tylko w trybie worker, bo tylko ta pula liczy, co workery zakończyły; opisywany stan nie może wystąpić tam, gdzie worker blokuje się na samej kolejce. Trzy wskaźniki są eksportowane w każdym trybie.

Zmarnowane oczekiwania

oxphp_admission_wait_wasted_total liczy pracę rozpoczętą, a nie wpisy opuszczające kolejkę, bo worker usuwający żądania, na które odpowiedziały już ich terminy, porusza kolejkę, nikogo nie obsługując. Licznik działa tylko przy budżecie na pułapie, bo gdy serwer już skrócił budżet, „pula niczego nie rozpoczęła” mówi więcej o oknie niż o puli: zdrowa pula czterech workerów z handlerami trwającymi ćwierć sekundy rozpoczyna jedno żądanie co 62 ms, więc na minimum większość oczekiwań kończy się między dwoma startami.

Koszt tego warunku zależy od tego, czy budżet się zmienia:

• Pula, która niczego nie rozpoczyna, nigdy nie osiąga liczby rozpoczętych żądań, na podstawie której decyduje kontroler, więc trzyma swój pułap, a ten licznik pozostaje aktywny.
• Pula wywołująca samą siebie rozpoczyna żądanie za każdym razem, gdy zewnętrzne żądanie rezygnuje ze swojego wewnętrznego wywołania. Gdy jej własni wywołujący są mniej cierpliwi niż jej handlery, budżet spada (zmierzono dwa zmniejszenia o połowę w ciągu kilku sekund), a ten licznik milknie po żądaniach, które przybyły przed spadkiem. Nic na tej stronie nie przejmuje wtedy jego roli: szukaj wzorca w wywołaniach wychodzących samej aplikacji. Tam, gdzie wywołujący są cierpliwi (wewnętrzny cron, sidecar z hojnym limitem czasu), nic nie zostaje porzucone, pułap się utrzymuje, a to właśnie ten licznik nazywa problem.

Klasyczną przyczyną jest aplikacja wywołująca przez HTTP ten sam serwer, ale licznik nie jest detektorem samowywołań: pula, której handlery trwają dłużej niż budżet, również niczego nie zwalnia w trakcie oczekiwania. W trybie worker rozróżnia je oxphp_worker_request_duration_us (czas handlera, bez oczekiwania w kolejce): handlery poniżej budżetu przy rosnącym liczniku oznaczają, że oczekiwania nie są jedynie kolejką za powolną pracą. Nie używaj do tego oxphp_request_duration_us: obejmuje on te odmowy, z których każda wnosi niemal cały budżet. Poza trybem worker użyj własnych pomiarów czasu aplikacji.

QUEUE_WAIT_TIMEOUT_MS=0 nie jest najkrótszą wersją krótszego budżetu: usuwa oczekiwanie na slot w kolejce, a oczekiwanie wewnątrz kolejki pozostawia nieograniczone, więc w puli, która niczego nie podejmuje, żądanie, które znajdzie wolny slot, nigdy nie dostaje odpowiedzi. Łącz 0 z QUEUE_CAPACITY na tyle małym, by kolejka była pełna, zanim zacznie to mieć znaczenie.

Co mówi log, gdy żądania są odrzucane

Nadzorca obserwuje cztery przyczyny przeciążenia z oxphp_admission_refused_total w tym samym jednosekundowym skanie i zgłasza epizod, a nie pojedyncze żądania, bo linia na każdą odmowę sama byłaby awarią. Pierwszy skan, który zobaczy ruch któregokolwiek z nich, loguje:

refused to liczba odrzucona przez ten jeden skan, z wyjątkiem pierwszego skanu, który ma kolejkę do obejrzenia — ten zgłasza wszystko odrzucone przed nim (pula wciąż ładująca aplikację, podczas gdy przybywające żądania się piętrzą, to prawdziwy epizod). Głębokość równa pojemności bez wolnego slotu to pula, która nie nadąża z pracą, a wait_budget_us wyraźnie poniżej wait_budget_ceiling_us mówi, że serwer już skrócił oczekiwanie; obie liczby są podane, bo budżet zepchnięty do minimum i budżet tak nisko skonfigurowany wyglądają osobno tak samo. Dane kolejki to migawka z chwili skanu, a refused obejmuje ostatnią sekundę, więc duże refused obok pustej kolejki to krótki wybuch, a nie sprzeczność.

Obie liczby są rozbite według przyczyny na cztery etykiety przeciążenia z oxphp_admission_refused_total, a nazwy pól są tworzone od liczby, którą rozbijają: refused_queue_full, refused_wait_timeout, refused_waiting_full i refused_waiting_bytes sumują się do refused, a powtórzenie i linia zamykająca poniżej niosą episode_refused_queue_full i trzy pokrewne pola, które sumują się do episode_refused. To przyczyna decyduje, po którą gałkę sięgnąć (wiersz tego licznika powyżej mówi, na co wskazuje każda z nich), a ten licznik jest serwowany tylko na INTERNAL_ADDR. Na instancji bez wewnętrznego listenera przyczynę wciąż można odczytać z tych pól oraz, tam gdzie śledzenie jest włączone, z atrybutu spana oxphp.shed_reason. Wszystkie cztery są zapisywane nawet przy zerze: to jawne 0 wyklucza daną przyczynę.

Dopóki epizod trwa, ostrzeżenie powtarza się jako PHP admission is still shedding requests under overload, nie częściej niż raz na minutę i tylko przy skanie, który sam odrzuca (więc przerwa może sięgnąć prawie dwóch minut), niosąc episode_refused (bieżącą sumę) obok refused z pojedynczego skanu. Powtórzenie rozbija według przyczyny sumę epizodu, a nie skanu. Ma to znaczenie, bo linia zamykająca jest zapisywana na poziomie INFO, poniżej warn, na którym logują konfiguracje produkcyjne, więc tam powtórzenie jest jedyną linią, która mówi, z czego epizod dotąd się składał, aż do skanu, przy którym zostało zapisane. Epizod, który kończy się w swojej pierwszej minucie, nie ma żadnego powtórzenia, a to, co zostanie odrzucone po ostatnim powtórzeniu, trafia tylko do linii zamykającej. Minuta bez żadnej odmowy kończy epizod, na poziomie INFO:

duration_ms liczy się do ostatniej odmowy, a nie do linii logu, więc zamykająca cicha minuta nie jest wliczana. Cicha minuta oznacza też, że przerwy krótsze niż minuta są łączone w jeden epizod, co ogranicza wyjście do najwyżej dwóch linii na minutę; wejście w epizod nie ma takiego opóźnienia, bo odmowa jest faktem, a nie próbką.

Raport jest emitowany w każdym trybie routingu i reaguje wyłącznie na cztery przyczyny przeciążenia, więc restart (shutting_down) ani zniknięta pula (pool_unavailable) nie ogłaszają się jako obciążenie. Nie ma wskaźnika dla tego stanu i żadna sonda nie jest o nim informowana: odrzucanie nigdy nie zmienia odpowiedzi /health/readiness, bo instancja odrzucająca 529 odpowiada szybko na działającej puli, a wycofywanie po kolei każdej przeciążonej repliki z rotacji zostawiłoby Service bez endpointów. Na przeciążenie odpowiadaj dodaniem pojemności. Zaklinowana pula również odrzuca żądania, a w trybie worker ten stan odpowiada 503, gdy utrzyma się przez minutę. Rozróżnia je kolejka: pula, która tylko nie nadąża, ją opróżnia, a zaklinowana — nie.

Metryki puli workerów

Metryki nadzorcy workerów

Obserwowalność na poziomie pojedynczego workera emitowana przez nadzorcę workerów. Każda seria niesie etykietę worker_id (indeks slotu). Pojawiają się one, gdy nadzorca śledzi stan poszczególnych workerów.

Histogram czasu oczekiwania w kolejce

Granice przedziałów (mikrosekundy): 50, 100, 250, 500, 1000, 2500, 5000, 10000, 50000, 100000, 250000, 500000, 1000000, +Inf.

Metryka mierzy czas spędzony na oczekiwaniu, na przyjęcie, a potem w kolejce, aż do chwili, gdy worker zdejmie żądanie z kolejki, więc odpowiada na pytanie „ile czasu minęło, zanim worker to podjął", a nie „ile trwało żądanie". Nic po tej chwili nie jest w niej ujęte: przygotowanie żądania przez workera, skrypt (do nagłówka odpowiedzi, w przypadku odpowiedzi strumieniowanej) i przekazanie odpowiedzi z powrotem do wątków I/O serwera wliczają się do oxphp_request_duration_us. To przekazanie nie jest darmowe: odpowiedź czeka, aż wątek I/O zostanie wybudzony albo upora się z pracą zakolejkowaną przed nią, więc przy tanim skrypcie czas po tym oczekiwaniu może kilkukrotnie przekraczać czas samego skryptu.

Rejestrowane jest tu tylko żądanie, które worker zdjął z kolejki w ramach jego budżetu. 529 odrzucone z powodu przeciążenia albo 503/500, gdy serwer się wyłącza lub pula zniknęła, są liczone w oxphp_admission_refused_total; 499 dla klienta, który odszedł, zanim dotarł do niego worker, jest liczone w oxphp_request_cancelled_total{reason="client_abort"} i w żadnej serii odmów.

Wysoki czas oczekiwania w kolejce oznacza, że żądania długo docierały do workera, co samo w sobie nie jest brakiem workerów: każdy odczyt obejmuje czas, jaki wątek workera potrzebuje, by dotrzeć do przekazanego mu żądania, a ten występuje także na nieobciążonym serwerze. Zanim podniesiesz PHP_WORKERS, sprawdź, czy żądania zastają wszystkie workery zajęte i czy maszyna ma wolne rdzenie: z workerami konkurują własne wątki I/O serwera, inne procesy i limit CPU kontenera. oxphp_busy_workers względem oxphp_workers_current odpowiada na pierwsze pytanie tylko częściowo: jest odczytywane w chwili scrape'a, więc wybuch, który wypełnia pulę między scrape'ami, widać tutaj, a tam nie, a w trybie worker wątek liczy się jako zajęty, dopóki niesie jakiekolwiek żądanie, nawet gdy handler tego żądania jest zawieszony, a wątek przyjmuje kolejne. Zakres sięga jednej sekundy, odpowiadając domyślnemu QUEUE_WAIT_TIMEOUT_MS, więc żądanie, które przed uruchomieniem zużyło większość swojego budżetu oczekiwania, zostaje policzone, a nie wrzucone do +Inf. Nic, co zostaje obsłużone, nie czeka dłużej niż budżet (po jego przekroczeniu żądanie jest odrzucane), więc podniesienie QUEUE_WAIT_TIMEOUT_MS to jedyne ustawienie, które z powrotem wprowadza oczekiwania do +Inf.

Metryki ograniczania liczby żądań

Metryki pamięci podręcznej plików statycznych

Metryki kompresji

Metryki trybu worker

Te metryki są emitowane tylko wtedy, gdy tryb worker jest aktywny (WORKER_MODE_ENABLED=true).

Liczniki globalne

Wskaźniki na poziomie workera

Histogram czasu trwania żądania workera

Granice przedziałów (mikrosekundy): 100, 250, 500, 1000, 2500, 5000, 10000, 25000, 50000, +Inf.

Ten histogram mierzy czas spędzony wewnątrz callbacka handlera PHP, z wyłączeniem czasu oczekiwania w kolejce. Użyj go, aby identyfikować wolne handlery i śledzić opóźnienia ogona w trybie worker.

Metryki puli asynchronicznej

Te metryki wymagają ustawienia ASYNC_WORKERS na wartość niezerową, a każda ma własną bramkę emisji: liczniki pojawiają się dopiero po tym, jak co najmniej jedno zadanie zostało wysłane lub odrzucone, wskaźniki _in_flight / _in_flight_limit pojawiają się, gdy pula podłączy swój licznik zadań w trakcie realizacji, a oxphp_async_output_discarded_bytes_total pojawia się dopiero po odrzuceniu jakiegoś wyjścia.

Metryki eksportu OpenTelemetry

Te metryki wymagają OTEL_ENABLED=true. Liczą partie spanów, które OxPHP wysyła do kolektora OTLP: spany żądań oraz spany APM, gdy włączona jest wtyczka APM.

Eksport jest ponawiany raz, gdy jego pierwsza próba nie powiedzie się bez odpowiedzi od kolektora w ciągu połowy OTEL_EXPORTER_OTLP_TIMEOUT lub jednej sekundy, zależnie od tego, co krótsze: połączenie zostało zresetowane lub zamknięte albo nie dało się go nawiązać. Zwykłą przyczyną jest load balancer lub NAT, który zerwał połączenie, gdy było bezczynne między eksportami. Status błędu, którym odpowiada sam kolektor, taki jak odrzucony klucz API lub dławienie (throttling), nie jest ponawiany: specyfikacja OTLP zabrania ponawiania większości z nich, a eksporter nie przekazuje dalej opóźnienia, o które prosi dławiący kolektor. Ponowienie, które dostarczy partię, jest liczone tylko w oxphp_otel_export_retries_total. Próba, która trafi na limit czasu eksportu, nie jest ponawiana, więc wolny kolektor nigdy nie dostaje tej samej partii dwa razy.

Ponowienie może jednak powodować duplikaty. Jeśli kolektor odebrał pierwszą próbę, zanim połączenie zostało zerwane, ponowienie dostarcza te spany po raz drugi, i z tego samego powodu eksport policzony jako nieudany mógł mimo wszystko dotrzeć do kolektora.

Spany, które tracer odrzuca przed eksportem, bo jego kolejka jest pełna (OTEL_BSP_MAX_QUEUE_SIZE, domyślnie 2048 spanów), nie są tutaj liczone.

Wskazówki do dashboardu Grafany

Poniższe zapytania PromQL są przydatne przy budowaniu dashboardów:

Częstotliwość żądań (żądania na sekundę):

Średni czas odpowiedzi (milisekundy):

Czas trwania żądania p99 (milisekundy):

Częstotliwość błędów (odpowiedzi 5xx jako procent):

Wykorzystanie puli workerów:

To prawdziwy ułamek między 0 a 1. Utrzymujące się wartości równe 1 oznaczają, że każdy worker jest zajęty, a kolejne nadchodzące żądania ustawiają się w kolejce. Zestaw go z rate(oxphp_admission_refused_total{reason=~"queue_full|wait_timeout|waiting_full|waiting_bytes"}[5m]), aby zobaczyć, czy ta zaległość zamienia się w odmowy, oraz z oxphp_pending_requests, aby zobaczyć, jak jest głęboka.

Nasycenie kolejki (częstotliwość odrzuceń na sekundę):

Czas oczekiwania w kolejce p99 (mikrosekundy):

Współczynnik trafień pamięci podręcznej plików statycznych:

Bajty zaoszczędzone dzięki kompresji na sekundę:

Opóźnienie p99 trybu worker (mikrosekundy):

Budżet oczekiwania zepchnięty poniżej pułapu (ułamek):

1 to stan normalny; każda niższa wartość oznacza, że serwer skraca oczekiwania pod przeciążeniem. Alertuj na ten stosunek, a nie na liczbę skopiowaną z QUEUE_WAIT_TIMEOUT_MS.

Wstrzymania pętli akceptującej (alert przy wartości niezerowej):

Częstotliwość recyklingu workerów (na minutę):

Średnie zużycie pamięci przez workera:

Konfiguracja scrape'owania Prometheus

Dodaj zadanie scrape'owania do swojego pliku prometheus.yml:

Dla wykrywania usług w Kubernetes:

Prompty dla Twojego agenta

Te prompty zakładają agenta z podłączonym serwerem MCP dokumentacji OxPHP — sam przeczyta strony, których potrzebuje.

Zobacz również

• Kontrole stanu — endpointy /health i /config na serwerze wewnętrznym
• Dokumentacja konfiguracji — wszystkie zmienne środowiskowe, w tym INTERNAL_ADDR
• Łagodne zamknięcie — jak drenowanie połączeń wpływa na oxphp_active_connections
• Tryb worker — trwałe workery i emitowane przez nie metryki