Understand the flow.
Take control.

All directives live in PHP's INI system. Scope decides where you can set it:

• PERDIR — settable in .htaccess (php_value, mod_php), .user.ini (FPM / lsphp) and per-vhost ini files, in addition to php.ini.
• SYSTEM — only meaningful in a global php.ini (or the ini include of the whole PHP binary). PERDIR directives can also be set in php.ini as the fleet-wide default.

Directives

Recipes

1. Disable for one site

In that site's ~/.user.ini (FPM/lsphp) or .htaccess (mod_php):

php_value phpray.enabled=0

Everything else on the server keeps tracing; this docroot is inert.

2. Profile one URL for a debugging session

Temporarily, for one site:

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

Visit /checkout/ a few times, read the per-function breakdown in the dashboard (phpray trace <domain> / dashboard → site → traces), then remove the three lines. Alternatively do this from the cloud console without touching ini: the collector pushes a time-boxed profile control message (see Ingest protocol, GET /v1/control).

3. Run with zero profiling

Fleet-wide in php.ini:

phpray.profile_mode=off

You keep always-on summaries, normal/full/alert traces and N+1/error detection, but the function-level observer never samples a request — minimal overhead (see Overhead).

Per-user rings (%u / %g)

By default one ring buffer serves the whole server. It is created at module start (0666 minus umask) and every PHP worker writes into it — fine on a single-tenant box, but on shared hosting a world-readable ring lets one customer's PHP read the traces (URIs, SQL, hosts) of every other customer.

Put %u (effective uid) and/or %g (effective gid) into phpray.shm_path and the extension switches to one private ring per user:

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

• Each worker attaches its ring lazily, at its first traced request — after PHP-FPM, lsphp or CGI has already switched to the site's user (module start still runs as root in the FPM master, so expanding %u there would be wrong). If the effective uid/gid changes later in the same process (mod_ruid2 style SAPIs), the worker re-attaches to the new user's ring.
• %u → the file is created 0600; %g alone → 0660. The collector runs as root and reads all of them: [input] shm_path = "/run/phpray/ring-*" (glob, collector 0.15+).
• The ring is opened if it already exists (workers of one user share it) and built only when missing or stale (different size/version). A new ring is prepared under a temporary name and published atomically, so a reader never sees a half-initialised header, and nothing is ever truncated in place.
• The directory is not created by the extension. Use a root-owned 1777 directory (/run/phpray, see the installer's CageFS mode); the extension refuses a file it does not own and never follows symlinks, so a file another user plants under your name is simply ignored.
• Per-user rings are never removed by PHP; they live on tmpfs and disappear at reboot. Memory: touched pages only, at most shm_size per active user (1 MB × 1000 active accounts = 1 GB worst case) — keep shm_size small here.
• phpray_ring_stats() returns path (the expanded, attached ring) and per_user; phpinfo() shows the same under "Ring Buffer".

%% is a literal %; any other %x is copied unchanged. On CloudLinux the ring must live in a directory shared with the cages — /dev/shm is private per cage, see Troubleshooting → CloudLinux / CageFS.

On-demand profiling table

phpray.control_path = /dev/shm/phpray-control — the shared-memory table the collector writes (from phpray control set … or from the Cloud console) and the extension reads at request start. Entries match by document root and URI prefix and switch full profiling on for a limited time, without touching php.ini. The table is shared by all users (read-only for PHP), so it takes no %u; on CageFS hosts point it at the shared directory too: phpray.control_path = /run/phpray/control.