$ guides / php-fpm ▌

PHP-FPM · OPERATIONS PLAYBOOK

PHP-FPM's one hard limit: every worker serves one request at a time, and when they are all busy the backlog turns into 502s

A process-based FastCGI runtime where the master hands each request to a single worker, maximum concurrency equals the number of workers, and one slow database or API can drain the entire pool in seconds. We trace how that model behaves under load, where saturation turns into dropped connections, and what to do when it does.

> Start with the monitoring checklist → # Jump to the full guide list

PHP-FPM's defaults get you serving pages in minutes, then hand you a worker pool that can go from healthy to all-busy in seconds.

The defaults work. Until a downstream database or API slows down, every worker blocks waiting on it, pm.max_children fills, and new requests pile into the socket backlog. Until that backlog reaches listen.backlog and the kernel silently drops connections — at which point nginx logs connect() failed (111: Connection refused) and users get a 502. Until pm.max_requests was left at 0 and a slow memory leak walks the box into the OOM killer. Until request_slowlog_timeout was never set, so you can see that workers are busy but never why. Until OPcache fills and every worker recompiles PHP on every request.

These guides are written for engineers who already run PHP-FPM behind nginx or Apache, not for people learning what FastCGI is. The goal is the mental model of how the pool actually behaves under load, the failure patterns that keep recurring, the monitoring story that catches them before they page anyone, and the runbooks you wish someone had handed you before your last incident.

How PHP-FPM actually runs in production

PHP-FPM is not a thread pool. It is a set of single-purpose OS processes where each worker handles exactly one request end to end, the master hands out connections from a kernel backlog, and workers spend most of their time blocked on I/O rather than computing. Most production failures live between these layers, not inside any one of them.

web server (nginx / Apache)

Terminates HTTP and opens a FastCGI connection per PHP request over a Unix or TCP socket. It can accept far more concurrent connections than FPM can serve, so <code>worker_connections</code> without rate limiting lets bursts through that the much smaller worker pool cannot absorb.

PROXY

socket + listen backlog

A kernel-managed queue (sized by <code>listen.backlog</code>) holds FastCGI connections until a worker is free. When it fills, the kernel drops new connections — invisible to FPM's own status page, which can never report more than the backlog size.

BACKLOG

master process

Maintains the scoreboard, forks and reaps workers, runs the process-manager strategy (static / dynamic / ondemand), and exposes the status and ping endpoints. It does almost no work itself; near-zero master CPU is normal.

MASTER

worker pool

Up to <code>pm.max_children</code> processes, each serving one request at a time. This is the hard concurrency ceiling: active workers = concurrent requests. When active hits max_children, the next request queues in the backlog.

WORKERS

PHP runtime + OPcache

Each worker runs a full PHP runtime; all workers share one OPcache shared-memory segment of compiled bytecode. A full or thrashing OPcache forces recompilation on every request and slows every worker at once — with nothing showing in the FPM status page.

RUNTIME

the request

The script executes under <code>memory_limit</code>, <code>request_slowlog_timeout</code>, and <code>request_terminate_timeout</code>. A stuck request with no terminate timeout occupies its worker forever, permanently shrinking the pool.

EXECUTE

downstream dependencies

Database, cache, external APIs, session files, filesystem. Workers block here holding a slot while using no CPU, so a slow dependency converts the whole pool into a traffic dam. N workers each open a connection — N database connections from this host alone.

DEPENDS

OS, memory, and lifecycle

Per-worker RSS accumulates across requests; <code>pm.max_requests</code> recycles workers to bound it. File descriptors, the cgroup memory limit, and the OOM killer sit underneath — and the OOM killer takes workers (or the master) with no warning in FPM's logs.

Why this matters: 'the site is slow' or 'we're getting 502s' can come from a saturated worker pool, a slow database holding every worker hostage, a full listen backlog dropping connections at the kernel, a memory leak walking toward the OOM killer, a segfaulting extension in a crash loop, or OPcache thrashing. The symptom rhymes but each layer has a different signal — and a different fix.

The failures you'll actually see

Most PHP-FPM incidents fall into a small set of recurring patterns. Recognise the shape, and triage gets dramatically faster.

CRITICAL

The worker traffic jam

Every worker is busy, active processes equals pm.max_children, and new requests pile into the socket backlog. As the backlog fills, the web server starts returning 502/504. Often CPU is low — the workers are blocked on I/O, not computing — so the box looks idle while the site is down.

active processes at pm.max_children, idle at 0
listen queue growing, max children reached incrementing
502 / 504 errors appearing in the web server log
CPU lower than expected (workers waiting, not computing)

Investigate →

CRITICAL

The slow-dependency drain

A database, API, cache, or NFS mount slows down. Requests that finished in 50ms now take seconds, each holding a worker hostage. The pool drains within seconds, the backlog fills, and users get errors — while the PHP application itself is fine, just waiting. This is the single most common PHP-FPM failure mode.

Slow-log stack traces pointing at PDO / curl / stream calls
Many workers with request duration far above baseline
active processes climbing to max_children at low CPU
Adding workers doesn't help — the new ones block too

Investigate →

CRITICAL

502 from a full backlog

The web server cannot reach the pool. Either the backlog overflowed and the kernel is refusing connections, the master is down, or the socket path/permissions are wrong. nginx logs connect() failed (Connection refused) and every affected request returns 502. The FPM status page may show listen queue = 0 because the drops happen below it, at the kernel.

connect() failed (111: Connection refused) in the nginx log
Kernel ListenOverflows / ListenDrops incrementing
Ping succeeds but connections still refused (backlog full)
502 across all PHP endpoints

Investigate →

ACTIVE

The memory-leak OOM spiral

Per-worker RSS climbs monotonically because pm.max_requests is 0 and workers never recycle. Total footprint creeps toward system (or cgroup) memory, swapping begins, then the OOM killer fires and takes workers — or the master — with no warning in FPM's logs. A restart fixes it for a while, then it recurs.

child N exited on signal 9 (SIGKILL) in the error log
Out of memory entries in dmesg / journalctl
Per-worker RSS growing over hours/days, no plateau
pm.max_requests = 0 (unlimited)

Investigate →

ACTIVE

The segfault crash loop

A native extension, corrupted OPcache, or bad code path crashes workers. The master respawns them, they hit the same path and die again, burning CPU on constant forking. If emergency_restart_threshold is set, the master restarts every pool — a brief total outage; if it isn't, the pool just runs degraded. The crashing request is usually visible in the per-worker request uri.

child N exited on signal 11 (SIGSEGV) in the error log
total processes fluctuating, accepted conn dropping
upstream prematurely closed connection in the nginx log
Deaths clustered on one URI / endpoint

Investigate →

IMMINENT

The max_children ceiling

The pool keeps hitting its worker limit and logging server reached pm.max_children setting (N), consider raising it. Each occurrence is a request that had to wait. Raising the limit is only safe if memory allows — avg_worker_RSS x max_children + OS overhead must stay under ~70% of RAM, or the fix becomes the OOM spiral.

server reached pm.max_children setting (N) in the error log
max children reached counter incrementing during normal traffic
max active processes pinned at pm.max_children
Idle processes stuck at pm.min_spare_servers

Investigate →

Choosing a tool

Best PHP-FPM Monitoring Tools: 10 Ranked (August 2026)

A ranked review of the tools teams actually shortlist here, what each one is genuinely good at, and how the pricing behaves as you scale.

Read the buyer's guide →

PHP-FPM monitoring maturity levels

PHP-FPM observability works in four practical levels. Each is a complete operation, not a stepping stone. Pick the level that matches how much your application matters. Most production pools should land at the second level.

Level 1: Survival

Know that something is wrong

Survival monitoring is the floor. With these signals you can answer one question: is the pool alive and is it serving requests? You will not learn what broke, but you will learn that something broke before users do. Survival is enough for dev pools and non-critical apps.

Master alive / ping response Is the master up and can a worker answer a trivial ping?
Active processes Is the pool at pm.max_children — i.e. saturated?
Listen queue depth Any sustained non-zero value means requests are queuing.
Web server 502 / 504 rate The external view — are users actually getting errors?
System memory Is the box close enough to full that an OOM kill is near?

Level 2: Operational

Diagnose most incidents on your own

Operational monitoring is what most production pools should target. Survival tells you something is wrong; operational tells you what. With this coverage your team can usually diagnose an incident on its own: saturation, slow dependencies, memory leaks, crashes, OPcache.

Idle processes Burst headroom; near-zero is one spike away from queuing.
Max children reached (rate) Each increment is a request that had to wait for a slot.
Per-worker RSS Monotonic growth is a memory leak; size the pool from it.
Worker death rate Normal max_requests recycling vs SIGSEGV / OOM deaths.
Slow log configured + rate request_slowlog_timeout tells you WHICH code is slow.
OPcache hit rate + memory Below 99% after warmup means recompilation on hot paths.
Accepted connections rate A sudden drop at steady traffic = workers not accepting.
Total FPM memory footprint avg RSS x max_children against RAM (or the cgroup limit).

Level 3: Mature

Catch problems before they become incidents

Mature monitoring catches problems before they wake anyone up. Backlog overflow the status page can't see, request-duration percentiles creeping, workers that stopped recycling, OPcache fragmenting after deploys. None of these page you on day one — they become incidents on day thirty.

Request duration distribution p50/p95/p99 from ?full — shift, not absolute values.
Worker age distribution Very old workers mean pm.max_requests recycling is broken.
Socket-level backlog via ss Kernel Recv-Q catches queuing between status-page polls.
Kernel ListenOverflows / Drops The only place silent backlog drops are visible.
OPcache wasted memory + evictions Fragmentation from deploys predicts thrash before it hits.
Composite pattern detection 'active = max_children AND listen queue > 0 for 60s'.
Per-pool monitoring Each pool independently — aggregates hide a single bad pool.
DB connection count correlation FPM workers x connections can exhaust the database first.

Level 4: Expert

Reactive instrumentation after real incidents

Expert signals enter your stack the day after a specific incident proved you needed them. Fork latency during bursts, phantom workers on abandoned requests, PSS accounting, interned-strings pressure, cgroup OOM events. Most teams never need every signal here. Add the ones your incident history says you do.

Fork latency (spawn to ready) In dynamic/ondemand, the delay that fills the backlog on bursts.
PSS shared vs private per worker smaps_rollup PSS — the only honest number for capacity math.
request_terminate_timeout kills Hung requests, not merely slow ones; permanent slot loss.
Phantom worker detection nginx timed out but the worker still runs a dead response.
OPcache interned strings buffer Separate from main OPcache memory and easily overlooked.
Realpath cache effectiveness Misses cause a stat() storm on every include.
cgroup memory.events.oom_kill In containers, the kill count FPM's own logs never show.
Session handler latency File-session lock waits between a user's parallel requests.

Operating mistakes worth avoiding

The traps PHP-FPM teams keep falling into. Each has a clear, well-known fix. Most teams only learn it after an incident.

Leaving pm.max_requests at 0 (unlimited)

The default in many distros, and the single most common PHP-FPM misconfiguration. It lets any memory leak — yours, an extension's, or the runtime's — accumulate forever until the OOM killer fires. Set <code>pm.max_requests</code> to 500-1000: a worker finishes its current request, delivers the response, then exits and is replaced. Near-zero cost, and the safety net that prevents the slow-motion OOM.

Not configuring the slow log

<code>request_slowlog_timeout</code> defaults to 0 (disabled) — the number-one monitoring gap in production. Without it you know that workers are piling up but not why. The slow log captures a stack trace showing exactly which script and call blocked. Set it on every production pool; even a 5-10 second threshold beats correlating FPM counts against database and application logs by hand.

Sizing pm.max_children by CPU cores instead of memory

Workers spend most of their time waiting on I/O, not computing, so a 4-core box can run 50-200 workers if memory allows. The correct formula is memory-based: <code>(RAM x 0.7 - OS overhead) / avg_worker_RSS</code>. Setting it by cores leaves capacity on the table; setting it too high drives straight into OOM. Measure per-worker PSS first, then choose a number.

Not monitoring the listen queue

Teams rely on the web server's 5xx rate, which only fires after the backlog is full and connections are refused. The listen queue gives minutes of warning: any sustained non-zero value means requests are already queuing. By the time you see 502s you are past the point where a graceful capacity response was possible.

Not setting request_terminate_timeout

With it at 0 (default), a single hung request — deadlocked connection, infinite loop, stalled API call — occupies a worker forever. Stuck workers accumulate like barnacles until <code>active + idle < max_children</code> and capacity silently erodes. A 30-60 second terminate timeout (application-dependent) prevents permanent worker loss. It is a different mechanism from PHP's <code>max_execution_time</code>, which does not cover I/O waits.

Ignoring OPcache in production

OPcache is shared memory, invisible to the FPM status page, and it degrades every worker at once. Running with <code>opcache.validate_timestamps = 1</code> (the development default that stat()s files on every request) or an undersized <code>opcache.memory_consumption</code> means constant recompilation. The classic symptom is 'everything looks normal but all requests are slow.' Monitor OPcache separately.

Ignoring session lock contention

File-based sessions take an exclusive <code>flock(LOCK_EX)</code> at <code>session_start()</code>, so concurrent requests from the same user — AJAX pages, SPAs, parallel API calls — serialize completely. It looks like worker exhaustion but is a lock on one session file. Call <code>session_write_close()</code> early, or move sessions to Redis/Memcached. Even read-only session access blocks other requests.

Monitoring only the FPM status page, not the kernel and web server

The status page cannot see dropped connections: when the backlog overflows, the kernel discards them silently and FPM never knows. You need kernel counters (<code>TcpExtListenOverflows</code>, <code>TcpExtListenDrops</code>) or <code>ss</code> Recv-Q for that, and the web server error log for the external view. A backlog overflow shows up as 'connection refused' in nginx and nowhere in FPM.

PHP-FPM runbooks in this section

Each guide is a focused runbook for one symptom or topic. Pick one when you have an incident, or use the categories to learn the area.

▸

Start here

▸

Worker pool saturation and capacity

▸

Slow requests, latency, and the slow log

▸

Worker memory, leaks, and OOM

▸

Worker crashes, exits, and restarts

▸

Process manager modes and pool sizing

▸

OPcache: hit rate, memory, and thrash

▸

Web server to FPM connectivity (502 / 504)

▸

Listen backlog, sockets, and file descriptors

▸

Sessions and request state

▸

Status page exposure and hardening

WHERE TO GO NEXT

Setting up PHP-FPM monitoring, or putting out a fire?

If you're starting from scratch, the monitoring checklist is the path of least regret. If you're mid-incident, jump straight to the symptom that matches what you're seeing.

> Start with the checklist > Back to Operations Guides