Up until now, we've mostly let the default www pool handle everything. That works fine for a blog or a small app, but in production, that's a recipe for disaster. If one heavy script—like a PDF generator or a massive CSV export—starts hogging all the PHP-FPM workers, your entire site goes down. You get those dreaded 504 Gateway Timeouts for every single user, even the ones just trying to load the homepage.

I've seen this happen more times than I care to admit. The fix is to create dedicated pools. Think of it as giving your "heavy" tasks their own lane on the highway so they don't cause a traffic jam for everyone else.

Isolating the Heavy Lifters

Let's say we have a specific set of scripts for generating monthly reports. Instead of letting them run in the default pool, I'm going to create a new pool configuration file. I usually put these in /etc/php/8.x/fpm/pool.d/. I'll call mine reports.conf.

[reports]
user = www-data
group = www-data
listen = /run/php/php8.2-fpm-reports.sock
listen.owner = www-data
listen.group = www-data

pm = dynamic
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3

Notice how I'm limiting pm.max_children to 5. I'm doing this intentionally. I don't want my report generator to spin up 50 processes and eat all the server's RAM, which would trigger the OOM (Out Of Memory) killer and possibly take down MySQL along with it.

The "502 Bad Gateway" Moment

Here is where I usually mess up the first time—and I did it just now while testing this. I restarted PHP-FPM, refreshed my report page, and got a 502 Bad Gateway. I spent five minutes checking the PHP logs, but there was nothing there. Why? Because the request never even reached PHP.

I forgot that Nginx doesn't magically know about my new pool. Nginx is still trying to send everything to the default php8.2-fpm.sock. I need to tell Nginx to route requests for the /reports URI to my new socket.

I'll jump into my Nginx site config and add this block:

location /reports {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.2-fpm-reports.sock;
}

After a systemctl reload nginx, everything clicks into place. Always remember: if you change the listen directive in FPM, you must update the fastcgi_pass in your web server config to match.

Hunting Down the Bottlenecks

Now that the report pool is isolated, I want to know why some reports are taking so long. Instead of guessing or peppering my code with microtime() calls, I'll use the PHP-FPM slow log. This is one of the most underrated features of FPM.

I'll add these two lines to my reports.conf pool:

request_slowlog_timeout = 5s
slowlog = /var/log/php-fpm/reports.slow.log

By setting this to 5 seconds, PHP-FPM will take a "snapshot" of the call stack for any request that takes longer than 5 seconds to execute. When a user complains a report is hanging, I don't have to guess; I can just tail that log and see exactly which function or database query is the culprit.

One quick tip: make sure the directory /var/log/php-fpm/ actually exists and is writable by the www-data user, otherwise FPM will fail to start or simply won't log anything.

📋 Practical Task

Exercise: Configuring a Dedicated Pool for an Image Processing Queue

You have a web application where users upload high-resolution images that need to be resized. Currently, these are handled by the main www pool, causing the rest of the site to lag during uploads.

Your Task: Create a PHP-FPM pool configuration for a new pool named [images]. Your configuration must meet the following requirements:

• Use a Unix socket located at /run/php/php-fpm-images.sock.
• Set the process manager to static (since image processing is predictable and resource-heavy).
• Limit the number of children to exactly 3 to prevent CPU exhaustion.
• Enable a slow log that triggers after 10 seconds, saving logs to /var/log/php-fpm/images.slow.log.
• Ensure the socket is owned by the www-data user and group.

Write out the full content of the images.conf file as it would appear in the pool.d directory.