Quickstart

Get metrics from your PHP-FPM pools in under 5 minutes.

Prerequisites

• PHP-FPM running with status page enabled
• Network access to PHP-FPM socket (Unix or TCP)

Step 1: Enable PHP-FPM Status

Ensure your PHP-FPM pool has the status page enabled. In your pool config (e.g., /etc/php/8.3/fpm/pool.d/www.conf):

pm.status_path = /status

Restart PHP-FPM after changes:

sudo systemctl restart php-fpm

Step 2: Start the Exporter

With automatic discovery (recommended):

fpm-exporter serve

The exporter will:

1. Discover running PHP-FPM processes
2. Parse their configurations
3. Start collecting metrics
4. Expose Prometheus endpoint on :9114

Step 3: Verify Metrics

curl http://localhost:9114/metrics

You should see metrics like:

# HELP phpfpm_active_processes The number of active PHP-FPM processes.
# TYPE phpfpm_active_processes gauge
phpfpm_active_processes{pool="www",socket="tcp://127.0.0.1:9000"} 2

# HELP phpfpm_idle_processes The number of idle PHP-FPM processes.
# TYPE phpfpm_idle_processes gauge
phpfpm_idle_processes{pool="www",socket="tcp://127.0.0.1:9000"} 3

Step 4: Configure Prometheus

Add to your prometheus.yml:

scrape_configs:
  - job_name: 'fpm-exporter'
    static_configs:
      - targets: ['localhost:9114']

Reload Prometheus:

curl -X POST http://localhost:9090/-/reload

Adding Laravel Monitoring

Monitor Laravel queue sizes and application state using one of these methods:

Shorthand (Quick Setup):

fpm-exporter serve --laravel MyApp:/var/www/html

Repeatable Flags (With Queues):

fpm-exporter serve \
  --laravel-site name=MyApp \
  --laravel-site path=/var/www/html \
  --laravel-site queues.redis=default,emails

Config File (Complex Setups):

Create laravel-sites.yaml:

laravel:
  - name: MyApp
    path: /var/www/html
    queues:
      redis:
        - default
        - emails

Run:

fpm-exporter serve --laravel-config laravel-sites.yaml

This exposes:

• laravel_queue_size{site="MyApp",connection="redis",queue="default"}
• laravel_app_info{site="MyApp",...}
• laravel_debug_mode{site="MyApp"}
• And more...

Debug Mode

Enable debug logging to troubleshoot issues:

fpm-exporter serve --debug

Or via environment variable:

CBOX_DEBUG=true fpm-exporter serve

Common Issues

No PHP-FPM Pools Discovered

1. Check PHP-FPM is running: pgrep php-fpm
2. Verify status path is configured in pool config
3. Try with debug mode to see discovery details

Permission Denied on Socket

Run exporter as the same user as PHP-FPM or add to the www-data group:

sudo usermod -a -G www-data $USER

Metrics Show 0 Values

Ensure pm.status_path is set and accessible. Test directly:

SCRIPT_NAME=/status \
SCRIPT_FILENAME=/status \
REQUEST_METHOD=GET \
cgi-fcgi -bind -connect /var/run/php-fpm.sock

Next Steps

• Configuration - Full configuration reference
• Metrics Reference - All available metrics
• Laravel Integration - Detailed Laravel setup