Zrozum przepływ.
Przejmij kontrolę.

Zacznij od phpray status — zobacz CLI. Polecenie pomaga wskazać pierwszy problem w opisanych scenariuszach.

Rozszerzenie nie ładuje się

php -m | grep phpray nic nie zwraca albo php -v kończy się błędem:

• Niezgodna wersja PHP. Plik .so jest przypisany do wersji; php8.3-glibc-x86_64 nie działa z PHP 8.2. Porównaj php -v z nazwą pliku.
• ZTS / NTS. Tryb bezpieczeństwa wątkowego musi być zgodny z modułem. Sprawdź php -i | grep Thread. Gotowe pliki opisane w dokumentacji są NTS. Opcja --enable-shared nie wybiera ZTS.
• Niezgodna libc. Alpine używa musl, wiele innych dystrybucji glibc. Obraz Alpine wymaga wariantu musl.
• Sprawdź komunikat loadera w error_log lub dmesg. Brakujące symbole zwykle wskazują niezgodną wersję lub build.

Brak śladów dla serwisu

Uruchom phpray status i phpray trace -d <domena> -n 5; typowe przyczyny po kolei:

• czy URI znajduje się w phpray.ignore_uris, także w lokalnym .user.ini
• czy phpray.mode=manual nie czeka na wyzwalacz; przełącz na smart lub uruchom sesję diagnostyczną
• czy phpray.enabled=0 nie wyłącza serwisu w jego konfiguracji PERDIR; lokalna konfiguracja nadpisuje php.ini
• czy żądanie nie było zbyt szybkie: domyślnie smart zapisuje normal od 200 ms; zmniejsz phpray.smart_threshold_normal albo użyj all
• czy phpray.profile_mode=off nie wyłącza jedynie tabeli komponentów; ślady nadal są dostępne, to oczekiwane zachowanie

Collector nie czyta shm

phpray status wskazuje działający collector, ale danych brak:

• phpray.shm_path/phpray.shm_size rozszerzenia i [input] shm_path collectora muszą być dokładnie takie same (różne wersje PHP z różnymi dołączanymi plikami ini to klasyczne rozjechanie); przy ringach per użytkownik (shm_path = /run/phpray/ring-%u) collector potrzebuje formy ze wzorcem shm_path = "/run/phpray/ring-*"
• sprawdź zgodność trybu: output_mode=file po jednej stronie i shm po drugiej nie tworzą wspólnego przepływu
• sprawdź wolne miejsce przez df -h /dev/shm
• ringi per użytkownik pojawiają się dopiero po pierwszym śledzonym żądaniu danego konta (ls -la /run/phpray/ pokazuje pliki ring-<uid> z prawami 0600)

Problemy uprawnień

• Katalog /var/lib/phpray musi być dostępny dla użytkownika collectora phpray. Przy zapisie plikowym (output_mode=file|both) użytkownik PHP, np. nobody, www-data lub UID konta lsphp, musi móc zapisywać katalog śladów. Na serwerach wielu użytkowników preferuj shm, aby PHP nie zapisywało katalogu bazy.
• ring per użytkownik (%u w shm_path) jest używany tylko wtedy, gdy plik jest zwykłym plikiem należącym do tego uid: plik albo dowiązanie podstawione przez innego użytkownika pod tą nazwą jest ignorowane (phpray_ring_stats() zwraca false); usuń je jako root

CloudLinux / CageFS

Objaw: rozszerzenie się ładuje, phpray status mówi „collector ok", ale ślady nie przychodzą — a /dev/shm/phpray na hoście pozostaje pusty (albo klatka tworzy własną kopię). Przyczyna: każdy użytkownik CageFS ma własny, pusty /dev/shm (odrębna przestrzeń montowań), więc ring pod /dev/shm jest niewidoczny dla collectora, a jeden ring zapisywalny dla wszystkich i tak pozwoliłby klientom czytać nawzajem swoje ślady. Użyj wspólnego katalogu i jednego ringu na użytkownika:

# 1. shared runtime dir, sticky and world-writable (survives reboots via tmpfiles)
install -d -m 1777 -o root -g root /run/phpray
echo 'd /run/phpray 1777 root root -' > /etc/tmpfiles.d/phpray.conf

# 2. mount it into every cage: one line without prefix in cagefs.mp
grep -qx '/run/phpray' /etc/cagefs/cagefs.mp || echo '/run/phpray' >> /etc/cagefs/cagefs.mp
cagefsctl --force-update        # server-wide: rebuilds the skeleton and remounts all users
                                # (cagefsctl --remount-all only remounts; CloudLinux documents it
                                # as the command to run after a cagefs.mp change — both are global)

INI rozszerzenia (każda wersja PHP, także /opt/alt/php*):

extension=phpray.so
phpray.enabled      = 0                       ; opt-in: phpray.enabled=1 in the account's .user.ini
phpray.output_mode  = shm
phpray.shm_path     = /run/phpray/ring-%u     ; one private 0600 ring per uid
phpray.shm_size     = 2097152                 ; per user — keep it small
phpray.control_path = /run/phpray/control     ; shared, read-only for PHP

Collector (/etc/phpray/collector.toml, collector 0.15+ czyta wzorzec):

[input]
shm_path     = "/run/phpray/ring-*"
control_path = "/run/phpray/control"

systemctl restart phpray-collector.

Sprawdzenie z wnętrza klatki, jako klient:

su -s /bin/bash <user> -c 'ls -ld /run/phpray && php -r "var_dump(phpray_ring_stats());"'
# after the first traced request of that site:
ls -la /run/phpray/            # ring-<uid>  -rw------- <user>
phpray status                  # collector: rings found

Instalator robi wszystko powyższe, gdy wykryje cagefsctl (install.sh --cagefs wymusza ten tryb, --no-cagefs go pomija), zob. Hosting współdzielony.

Dwie awarie warte zapamiętania

Obie wynikają z jednostki systemd i obie wystąpiły na działającym serwerze z CloudLinuksem.

• Ring buffer … not usable yet: read-only file system w logu collectora. Jednostka działa z ProtectSystem=strict, co czyni /run tylko do odczytu, więc /run/phpray musi być wymieniony w ReadWritePaths. Jednostki od PHPRay 0.15 już go zawierają.
• PHP przestaje pisać do ringu po restarcie collectora — phpray_ring_stats() zwraca false wewnątrz klatki, choć z hosta katalog wygląda zupełnie poprawnie. RuntimeDirectory=phpray kasuje /run/phpray przy zatrzymaniu usługi; klatki zostają z montowaniem usuniętego i-węzła. Porównaj je:

stat -c %i /run/phpray                                        # host
su -l <account> -s /bin/bash -c 'stat -c %i /run/phpray'      # inside the cage

Różne numery oznaczają nieaktualne montowanie: naprawia je cagefsctl --remount-all. Jednostki od PHPRay 0.15 mają RuntimeDirectoryPreserve=yes i RuntimeDirectoryMode=1777, więc katalog przeżywa restarty; starsza jednostka wymaga nakładki:

# /etc/systemd/system/phpray-collector.service.d/cagefs.conf
[Service]
RuntimeDirectoryMode=1777
RuntimeDirectoryPreserve=yes
ReadWritePaths=-/run/phpray

Długo żyjące workery PHP trzymają .so załadowany przy starcie: po podmianie rozszerzenia przeładuj workery danego konta (pkill -u <konto> -f lsphp) zamiast restartować cały serwer WWW.

Przygotowanie zgłoszenia błędu

phpray report -o phpray-report.txt
journalctl -u phpray-collector --since "10 min ago" >> phpray-report.txt

Dołącz raport, wersję PHP i dystrybucji oraz dokładny wynik php -i | grep -E "phpray|extension_dir". Przed przekazaniem sprawdź, czy raport nie zawiera danych, których nie chcesz udostępniać.