Skip to content

PHP-FPM Monitoring

CLI Pal can monitor your PHP-FPM pools, providing real-time metrics and slow request traces to help identify performance bottlenecks.

Requirements

  • PHP-FPM (not mod_php)
  • pm.status_path enabled in PHP-FPM config
  • Agent v0.1.2+

Native FastCGI - No Proxy Needed!

CLI Pal communicates directly with PHP-FPM sockets using the FastCGI protocol. No Apache/Nginx proxy configuration required!

Enabling PHP Monitoring

During Installation

Add the --enable-php-monitoring flag when installing the agent:

curl -sSL https://clipal.me/install.sh | sudo bash -s -- \
  --token=YOUR_TOKEN \
  --mysql-root-password=YOUR_PASSWORD \
  --enable-php-monitoring

The installer will automatically detect your PHP-FPM socket and verify the connection.

Manual Socket Path

If auto-detection fails, specify the socket path:

curl -sSL https://clipal.me/install.sh | sudo bash -s -- \
  --token=YOUR_TOKEN \
  --enable-php-monitoring \
  --php-socket=unix:///var/run/php/php8.2-fpm.sock

On Existing Installation

Edit /opt/clipal/clipal.conf and add:

# PHP-FPM Monitoring (native FastCGI)
php_enabled=true
php_fpm_socket=unix:///var/run/php/php8.2-fpm.sock
php_fpm_status_path=/status
php_fpm_slow_log=/var/log/php-fpm/www-slow.log

Then restart the agent:

sudo systemctl restart clipal-agent

PHP-FPM Configuration

Enable Status Page

The only PHP-FPM configuration required is enabling the status page. Edit your pool configuration:

File: /etc/php/8.x/fpm/pool.d/www.conf

pm.status_path = /status

File: /etc/php-fpm.d/www.conf

pm.status_path = /status

File: /usr/local/apps/php83/etc/php-fpm.conf

pm.status_path = /status

Restart PHP-FPM:

sudo systemctl restart php-fpm
# or for specific version:
sudo systemctl restart php8.2-fpm

No Web Server Config Needed

Unlike other monitoring solutions, CLI Pal does not require you to configure Apache or Nginx to proxy the status page. The agent communicates directly with PHP-FPM.

In your pool config (www.conf):

; Log slow requests (taking longer than 5 seconds)
slowlog = /var/log/php-fpm/www-slow.log
request_slowlog_timeout = 5s

; Include actual stack traces
request_slowlog_trace_depth = 20

Socket Locations

The installer auto-detects sockets in these common locations:

Distribution/Panel Socket Path
Ubuntu/Debian /var/run/php/php8.x-fpm.sock
CentOS/RHEL /var/run/php-fpm/www.sock
Webuzo /usr/local/apps/php8x/var/run/php-fpm.sock
cPanel /opt/cpanel/ea-php8x/root/var/run/php-fpm.sock
Plesk /var/run/plesk-php8x-fpm.sock

Find your socket manually:

# Find socket files
find /var/run -name "*.sock" 2>/dev/null | grep php

# Or check running processes
ps aux | grep php-fpm

What Gets Monitored

Metric Description
Active Processes Currently handling requests
Idle Processes Available to handle new requests
Listen Queue Requests waiting for a free process (0 is ideal)
Max Children Reached Times pool ran out of workers
Accepted Connections Total connections since start
Slow Requests Requests exceeding slowlog threshold

Slow Request Traces

When slowlog is enabled, CLI Pal captures stack traces of slow PHP requests:

  • Scripts taking longer than request_slowlog_timeout
  • Full stack traces showing which functions were running
  • Automatic deduplication of repeated traces

View these in the PHP Monitor page under the Slow Traces tab.

Multi-Pool Configuration

For servers with multiple PHP-FPM pools:

# /opt/clipal/clipal.conf
php_enabled=true
php_fpm_pools=[{"name":"www","socket":"unix:///var/run/php/php8.2-fpm.sock","status_path":"/status","slow_log":"/var/log/php-fpm/www-slow.log"},{"name":"api","socket":"tcp://127.0.0.1:9001","status_path":"/status","slow_log":"/var/log/php-fpm/api-slow.log"}]

TCP Connections

If your PHP-FPM listens on TCP instead of a Unix socket:

php_fpm_socket=tcp://127.0.0.1:9000

Troubleshooting

Socket not found

❌ Could not find PHP-FPM socket

Solution: Specify the socket path manually:

# Find your socket
find /var/run -name "*.sock" 2>/dev/null | grep php

# Re-run installer with socket path
--php-socket=unix:///path/to/your/socket.sock

Status page not found

❌ PHP-FPM verification failed: Status page not found

Solution: Enable the status page in PHP-FPM config:

pm.status_path = /status

Then restart PHP-FPM: systemctl restart php-fpm

Permission denied

ERROR: Cannot connect - Permission denied

Solution: Check socket permissions:

ls -la /var/run/php/php8.2-fpm.sock

The agent runs as root, so this is rare. Check if SELinux or AppArmor is blocking access.

No metrics appearing

  • Check agent logs: journalctl -u clipal-agent -f
  • Ensure php_enabled=true is in the config
  • Verify the socket path is correct

Slowlog not capturing traces

  • Verify slowlog path is correct and readable
  • Check request_slowlog_timeout is set in PHP-FPM config
  • Ensure the log directory exists and is writable

Migration from v0.1.1

If you previously used the HTTP URL method (php_fpm_status_url), update your config:

  1. Remove: php_fpm_status_url=http://...
  2. Add: php_fpm_socket=unix:///var/run/php/php8.2-fpm.sock
  3. Restart: systemctl restart clipal-agent

You can now remove any Apache/Nginx proxy configuration you added for the status page.