Skip to content

Troubleshooting

Start with phpray status (see CLI) — it names the first thing that is wrong in every case below.

Extension not loading

php -m | grep phpray prints nothing, or php -v fails:

  • Wrong PHP version — the .so in the release is per version (php8.3-glibc-x86_64 will not load under 8.2). Match php -v to the artifact name.
  • ZTS vs NTS — build with --enable-shared (ZTS) needs the ZTS variant; most distro PHP is NTS. php -i | grep Thread tells you.
  • Wrong libc — musl (Alpine) vs glibc (everything else). Alpine containers need the musl artifact.
  • Check error_log / dmesg for the loader message (missing symbols → wrong version or build).

No traces for a site

Run phpray diag <domain>; common causes in order:

  • the URI is in phpray.ignore_uris (or the site's .user.ini sets it)
  • phpray.mode=manual and no trigger is active (console/CLI) — switch to smart or fire a profile
  • phpray.enabled=0 in a .user.ini/.htaccess closer to the docroot (PERDIR directives override php.ini; the closest file wins)
  • the request was fast — smart only stores normal at 200 ms and up; lower phpray.smart_threshold_normal or use all
  • phpray.profile_mode=off — traces still appear, just without the components table (expected, not a fault)

Collector not reading shm

phpray status shows "collector ok" but no data:

  • the extension's phpray.shm_path/phpray.shm_size and the collector's [reader].shm_path must match exactly (different PHP versions with different ini includes are a classic split)
  • output_mode=file on one side, shm on the other
  • shm on a full /dev/shm — check df -h /dev/shm

Permission issues

  • /var/lib/phpray must be owned by the phpray collector user; if the extension writes files (output_mode=file|both), the PHP user (e.g. nobody, www-data, the per-user lsphp uid) must be able to write it — on multi-user boxes use shm mode so PHP never writes to the storage dir
  • on CageFS hosts the collector needs the shm path in the per-user allow list (/opt/cpanel/cloudlinux/… → lscpu.conf/CageFS templates)

Collecting a bug report

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

Send the report, your PHP version and distro, and the exact php -i | grep -E "phpray|extension_dir" output.