Konfiguracja rozszerzenia — INI

configuration/extension

Konfiguracja rozszerzenia — INI

Wszystkie dyrektywy należą do systemu INI PHP. Zakres określa miejsce konfiguracji:

PERDIR — .htaccess (php_value, mod_php), .user.ini (FPM / lsphp), pliki INI wirtualnego hosta oraz php.ini.
SYSTEM — tylko globalny php.ini lub plik włączany dla całego interpretera PHP. Dyrektywy PERDIR również można ustawić w php.ini jako domyślne dla floty.

Dyrektywy

Dyrektywa	Zakres	Domyślnie	Znaczenie
`phpray.enabled`	PERDIR	`1`	Główny przełącznik. `0` wyłącza tracing i zapis danych rozszerzenia.
`phpray.mode`	PERDIR	`smart`	`smart` dobiera poziom do czasu żądania, `all` tworzy pełny ślad każdego żądania, `manual` działa po wyzwoleniu z konsoli lub CLI.
`phpray.smart_threshold_normal`	PERDIR	`200`	ms. Wolniejsze żądania otrzymują ślad `normal`.
`phpray.smart_threshold_full`	PERDIR	`1000`	ms. Wolniejsze żądania otrzymują ślad `full`.
`phpray.smart_threshold_alert`	PERDIR	`3000`	ms. Wolniejsze żądania otrzymują ślad `alert`; nie jest on próbkowany na etapie lokalnej kwalifikacji.
`phpray.manual_sample_rate`	PERDIR	`10`	Procent żądań śledzonych w trybie `manual`, gdy aktywny jest wyzwalacz.
`phpray.always_trace_errors`	PERDIR	`1`	`1` nadaje co najmniej poziom `normal` także szybkim żądaniom z błędem PHP.
`phpray.ignore_uris`	PERDIR	`""`	Prefiksy URI oddzielone przecinkami lub ``, wyłączone ze śledzenia, np. `/wp-cron.php,/assets/`.
`phpray.trace_cli`	SYSTEM	`0`	`1` włącza także śledzenie procesów CLI; opis źródłowy wymienia również SOAP i FPM.
`phpray.emit_header`	PERDIR	`1`	Dodaje nagłówek odpowiedzi `X-PHPRay: <level>` dla proxy i systemów logowania.
`phpray.capture_errors`	PERDIR	`1`	Przechwytuje błędy, ostrzeżenia i notices PHP do rekordu śladu.
`phpray.output_mode`	SYSTEM	`file`	`file` zapisuje JSONL do `output_path`, `shm` do pamięci współdzielonej dla collectora, `both` w oba miejsca.
`phpray.output_path`	SYSTEM	`/tmp/phpray.jsonl`	Plik JSONL ze śladami, jeden rekord na linię (przy `file` lub `both`).
`phpray.shm_path`	SYSTEM	`/dev/shm/phpray`	Ścieżka bufora pierścieniowego w pamięci współdzielonej. Może zawierać `%u` (efektywny uid) i `%g` (efektywny gid): wtedy każdy użytkownik dostaje własny, prywatny ring — zob. Ringi per użytkownik.
`phpray.shm_size`	SYSTEM	`33554432`	Rozmiar ringu w bajtach (32 MB). Przy ringach per użytkownik to rozmiar ringu każdego konta — tam używaj 1–2 MB.
`phpray.health_path`	SYSTEM	`/tmp/phpray_health`	Plik stanu do odtwarzania po awarii (liczniki awarii, flaga automatycznego wyłączenia). Przyjmuje te same znaczniki `%u` / `%g`; z `%u` powstaje z prawami `0600` i jest używany tylko wtedy, gdy należy do tego uid.
`phpray.profile_functions`	SYSTEM	`1`	`1` rejestruje observer wywołań funkcji przy starcie, wymagany do profilowania. Próbkowanie zależy od trybu profilu.
`phpray.profile_mode`	PERDIR	`sample`	`off` wyłącza profilowanie, `sample` losuje według `profile_sample_rate`, `url` wybiera URI pasujące do `profile_url`, `all` obejmuje każde żądanie.
`phpray.profile_sample_rate`	PERDIR	`3`	Procent żądań z profilem na poziomie funkcji.
`phpray.profile_url`	PERDIR	`""`	Prefiksy URI do profilowania przy `profile_mode=url`, oddzielone przecinkami, np. `/checkout/,/cart/`.
`phpray.profile_max_components`	SYSTEM	`64`	Maksymalna liczba różnych komponentów (wtyczek / funkcji) w jednym śladzie.
`phpray.crash_threshold`	SYSTEM	`3`	odtwarzanie po awarii: tyle awarii PHP (SIGSEGV/SIGBUS/SIGABRT) w oknie `crash_window` wyłącza rozszerzenie do czasu usunięcia pliku stanu albo wywołania `phpray_health_reset()`.
`phpray.crash_window`	SYSTEM	`60`	Okno czasowe progu awarii w sekundach.

Przykłady konfiguracji

1. Wyłączenie dla jednego serwisu

W pliku .user.ini serwisu (FPM / lsphp) użyj poniższej składni INI. W mod_php odpowiednikiem w .htaccess jest php_value phpray.enabled 0.

Przykład referencyjny

php_value phpray.enabled=0

Pozostałe serwisy nadal są śledzone; ten docroot pozostaje wyłączony.

2. Profilowanie jednego URL podczas diagnostyki

Tymczasowo, dla jednego serwisu, w pliku .user.ini:

Przykład referencyjny

php_value phpray.profile_mode=url
php_value phpray.profile_url=/checkout/
php_value phpray.profile_sample_rate=100

Otwórz kilka razy /checkout/, odczytaj profil w dashboardzie (serwis → ślady) lub phpray trace <domain>, a następnie usuń trzy linie. Alternatywnie użyj ograniczonego czasowo komunikatu profile z konsoli Cloud; zobacz protokół ingest, GET /v1/control.

3. Praca bez profilowania funkcji

Dla całej floty w php.ini:

Przykład referencyjny

phpray.profile_mode=off

Pozostają podsumowania always-on, ślady normal/full/alert oraz wykrywanie N+1 i błędów. Observer nie próbkuje żądań na poziomie funkcji. Zobacz Narzut.

Ringi per użytkownik (`%u` / `%g`)

Domyślnie jeden bufor pierścieniowy obsługuje cały serwer. Powstaje przy starcie modułu (0666 minus umask) i piszą do niego wszystkie procesy PHP — to w porządku na maszynie jednego właściciela, ale na hostingu współdzielonym ring czytelny dla wszystkich pozwala PHP jednego klienta czytać ślady (adresy URL, SQL, hosty) wszystkich pozostałych.

Wstaw %u (efektywny uid) lub %g (efektywny gid) do phpray.shm_path, a rozszerzenie przełączy się na jeden prywatny ring na użytkownika:

Przykład referencyjny

phpray.output_mode = shm
phpray.shm_path    = /run/phpray/ring-%u
phpray.shm_size    = 2097152

Każdy worker podpina swój ring leniwie, przy pierwszym śledzonym żądaniu — już po tym, jak PHP-FPM, lsphp albo CGI przełączyło się na użytkownika serwisu (start modułu wciąż działa jako root w nadrzędnym procesie FPM, więc rozwinięcie %u w tym miejscu byłoby błędne). Jeśli efektywny uid/gid zmieni się później w tym samym procesie (SAPI w stylu mod_ruid2), worker przepina się na ring nowego użytkownika.
%u → plik powstaje z prawami 0600; samo %g → 0660. Collector działa jako root i czyta je wszystkie: [input] shm_path = "/run/phpray/ring-*" (collector 0.15+).
Ring jest otwierany, jeśli już istnieje (workery jednego użytkownika go współdzielą), a budowany tylko wtedy, gdy go brakuje albo jest nieaktualny (inny rozmiar lub wersja). Nowy ring powstaje pod nazwą tymczasową i jest publikowany atomowo, więc czytający nigdy nie zobaczy w połowie zainicjowanego nagłówka i nic nie jest obcinane w miejscu.
Katalogu nie tworzy rozszerzenie. Użyj katalogu należącego do roota z prawami 1777 (/run/phpray, zob. tryb CageFS instalatora); rozszerzenie odrzuca plik, który nie należy do danego konta, i nigdy nie podąża za dowiązaniami, więc plik podstawiony przez innego użytkownika pod Twoją nazwą jest po prostu pomijany.
Ringi per użytkownik nie są nigdy usuwane przez PHP; leżą na tmpfs i znikają po restarcie maszyny. Pamięć: tylko dotknięte strony, najwyżej shm_size na aktywnego użytkownika (1 MB × 1000 aktywnych kont = 1 GB w najgorszym razie) — trzymaj tu małe shm_size.
phpray_ring_stats() zwraca path (rozwiniętą ścieżkę podpiętego ringu) i per_user; phpinfo() pokazuje to samo w sekcji „Ring Buffer".

%% oznacza dosłowny znak %; każde inne %x jest przepisywane bez zmian. Na CloudLinuksie ring musi leżeć w katalogu współdzielonym z klatkami — /dev/shm jest w każdej klatce osobny i pusty, zob. Rozwiązywanie problemów.

Tabela profilowania na żądanie

phpray.control_path = /dev/shm/phpray-control — tabela w pamięci współdzielonej zapisywana przez collector (poleceniem phpray control set … albo z konsoli Cloud), którą rozszerzenie odczytuje na starcie żądania. Wpisy dopasowywane są po katalogu głównym dokumentów i prefiksie URI; włączają pełne profilowanie na ograniczony czas, bez zmiany php.ini.

Źródło: docs-site/docs/configuration/extension.md · PHPRay 0.14
Wersja polska jest tłumaczeniem angielskiego oryginału; parametry i przykłady kodu pozostają w oryginalnej składni.

Zacznij od konkretu.

Zrozum przepływ.
Przejmij kontrolę.