How to enable the PHP-FPM status page

Enabling the PHP-FPM status page gives a live view of pool health before upstream timeouts, 502 responses, or vague application slowdowns turn into guesswork. Queue depth, worker counts, accepted connections, and slow-request counters make it easier to tell whether the bottleneck is the PHP pool itself or a different layer in the request path.

A pool answers status requests only after pm.status_path is set in that pool configuration and the web server forwards the matching URI directly to the same FastCGI socket or TCP listener. Current PHP documentation also supports pm.status_listen as a separate status-only listener, and the endpoint can return plain text, JSON, XML, HTML, or OpenMetrics output, with optional full process details.

The steps below use the common Debian or Ubuntu packaged layout with Apache proxying to the same PHP-FPM pool that serves the site. Keep the status URI restricted to localhost or trusted monitoring addresses, make sure rewrite rules do not swallow the endpoint, and validate both PHP-FPM and Apache before reloading either service.

1. Locate the PHP-FPM pool file that serves the site.

   $ ls /etc/php/*/fpm/pool.d/*.conf /etc/php-fpm.d/*.conf 2>/dev/null
   /etc/php/8.3/fpm/pool.d/www.conf

   Edit the pool that actually serves the application instead of assuming the default www pool. On RHEL-family hosts, the default pool file is usually /etc/php-fpm.d/www.conf.

2. Create a timestamped backup of the target pool file before editing it.

   $ sudo cp /etc/php/8.3/fpm/pool.d/www.conf /etc/php/8.3/fpm/pool.d/www.conf.bak-$(date +%Y%m%d%H%M%S)

   A broken pool file can keep PHP-FPM from reloading cleanly, so a rollback copy shortens recovery time.

3. Open the target pool file in a text editor.

   $ sudo vi /etc/php/8.3/fpm/pool.d/www.conf

   Use the discovered path when the host installs a different PHP branch or the unversioned /etc/php-fpm.d layout.

   Related: How to find PHP configuration files

4. Add the status-page directive inside the selected pool section.

   pm.status_path = /php-fpm-status

   The value must start with a leading slash and it must match the URI that the web server forwards to the same pool listener. Use pm.status_listen instead when health checks need a separate listener that can answer even if the main pool is saturated.

5. Test the PHP-FPM configuration before reloading the service.

   $ sudo php-fpm8.3 -tt 2>&1 | grep -E 'listen =|pm.status_path =|configuration file'
   [26-Mar-2026 02:20:24] NOTICE:     listen = /run/php/php8.3-fpm.sock
   [26-Mar-2026 02:20:24] NOTICE:     pm.status_path = /php-fpm-status
   [26-Mar-2026 02:20:24] NOTICE: configuration file /etc/php/8.3/fpm/php-fpm.conf test is successful

   Use the binary that matches the installed package set, such as php-fpm8.4 on a newer Debian or Ubuntu host or the unversioned php-fpm binary on RHEL-family systems. The -tt check prints the effective pool values as well as the final syntax result.

   Do not reload the service until the test is successful.

6. Reload the PHP-FPM service so the pool starts recognizing the status URI.

   $ sudo systemctl reload php8.3-fpm

   On RHEL-family hosts, the unit is commonly php-fpm.

   Related: How to manage the PHP-FPM service in Linux

7. Open the active Apache site or server configuration that already proxies the application to the target pool.

   $ sudo vi /etc/apache2/sites-available/portal.example.test.conf

   Use the active virtual-host or server file instead of dropping the status mapping into an unrelated site definition.

   Related: Understanding Apache web server configuration files

8. Add a dedicated Apache location rule that passes the status URI directly to the same PHP-FPM listener.

   <Location "/php-fpm-status">
       Require local
       ProxyPass "unix:/run/php/php8.3-fpm.sock|fcgi://localhost/"
   </Location>

   Keep the socket or TCP address aligned with the pool listen value reported by the PHP-FPM test output. An exact Location block is sufficient for this endpoint because the goal is one fixed URI, not a regex match.

   Place the mapping ahead of rewrite rules or front-controller fallbacks that would otherwise turn /php-fpm-status into an application request.

9. Test the Apache configuration before reloading it.

   $ sudo apachectl configtest
   Syntax OK

   Use apache2ctl configtest or httpd -t when the platform does not provide apachectl.

   Related: How to test your Apache configuration

10. Reload the Apache service so the status mapping becomes reachable.

    $ sudo systemctl reload apache2

    On RHEL-family hosts, the unit is usually httpd.

    Related: How to manage the Apache web server service

11. Query the status URI from localhost to confirm that the pool metrics are exposed.

    $ curl -s -H 'Host: portal.example.test' http://127.0.0.1/php-fpm-status
    pool:                 www
    process manager:      dynamic
    start time:           29/Mar/2026:12:31:18 +0000
    start since:          94
    accepted conn:        27
    listen queue:         0
    max listen queue:     1
    listen queue len:     4096
    idle processes:       1
    active processes:     1
    total processes:      2
    max active processes: 2
    max children reached: 0
    slow requests:        0

    The counters, queue length, and timestamps vary with pool settings and live traffic. The important result is a real PHP-FPM status block instead of application output, a rewrite target, or an error response.

    Add the virtual-host name with a Host header when the status mapping lives inside a name-based site definition. Switch to the exact site URL instead of 127.0.0.1 when the endpoint is only exposed on HTTPS or behind an internal reverse proxy. The same endpoint also supports ?full, ?json, ?xml, ?html, and ?openmetrics query parameters on current PHP-FPM releases.