$ guides / php-fpm / php-fpm-monitoring-checklist ▌

Operations Guides

PHP-FPM monitoring checklist: the signals every production pool needs

PHP-FPM is a process-based concurrency model. Each worker handles exactly one request at a time, so the worker pool is the binding constraint. When all workers are occupied, new requests queue in the socket backlog. Once that fills, the kernel drops connections silently. Every PHP-FPM incident is a story about worker capacity, worker health, or what workers are blocked on.

This checklist organizes production signals into four maturity levels: survival, operational, mature, and expert. Use it as a gap audit, or as a triage guide during incidents when workers are exhausted or the site returns 502s.

The levels are cumulative. If your Level 1 signals are broken, the higher levels will mislead you.

The four maturity levels

flowchart TD
    L1["Level 1 - Survival
master alive, active processes, listen queue, 502s, memory"]
    L2["Level 2 - Operational
idle workers, max_children reached, RSS, slow log, OPcache"]
    L3["Level 3 - Mature
per-worker duration, URI analysis, kernel drops, composite patterns"]
    L4["Level 4 - Expert
PSS, fork latency, phantom workers, socket state, session locks"]

    L1 --> L2 --> L3 --> L4

Level 1 catches “FPM is down.” Level 2 catches “FPM is saturated or leaking.” Level 3 catches “FPM is about to be saturated” and “which endpoint is causing it.” Level 4 catches the capacity erosion and timeout mismatches that cause recurring incidents without obvious symptoms.

Level 1: survival

Five signals. If you monitor nothing else, monitor these.

Signal	What it tells you	Warning sign
Master alive / ping	The master is running and the socket accepts connections	Ping unreachable for more than 2 minutes during live traffic
Active processes	How many workers are handling requests right now	Sustained at 100% of pm.max_children
Listen queue depth	Requests waiting in the backlog for a free worker	Any sustained non-zero value
Web server 502/504 rate	Users getting errors because FPM is unreachable or timed out	Any sustained 502 rate reaching users
System memory	OOM is approaching	Available memory declining, any swap usage

Ping confirms that a worker can service a FastCGI request, not that your application can run. The master accepts new sockets, but the ping response is produced by a worker; the endpoint returns a static response without executing application code. Under saturation, ping may be slow (hundreds of milliseconds) but still succeed. A slow ping is not a failure. A missing ping for more than two minutes during live traffic is.

The listen queue is the earliest direct signal of user-facing degradation. It goes non-zero before 502s appear. If you only alert on 5xx rates, you are alerting after the backlog is full and connections are already being dropped.

Suppress alerts for the first 120 seconds after an intentional restart or reload. During a SIGUSR2 graceful reload, there is a transition window where workers drain and respawn. Transient 502s and listen queue spikes during this window are expected.

Level 2: operational

These signals tell you whether FPM is healthy under load, approaching capacity, or slowly breaking. Missing any of these leaves you blind to a common failure mode.

Signal	What it tells you	Warning sign
Idle processes	Available headroom for bursts	Sustained near zero in dynamic or static mode
Total processes	Process manager is functioning	Static pool with fewer than max_children workers
Max children reached	PM tried to spawn but hit the ceiling	Counter incrementing during normal traffic
Accepted connections (counter)	Inbound throughput	Sudden drop while web server still receives traffic
Slow requests (counter)	Application-level slowness, which code is blocked	Rate above 2x rolling average
Per-worker RSS	Memory leak detection	Monotonic growth over hours or days
Worker death / signal exits	Stability, extension bugs	Any SIGSEGV (signal 11) or SIGBUS (signal 7)
OPcache hit rate	Compilation efficiency	Below 99% after warmup

The slow log is the most diagnostic signal in the FPM surface, and it is disabled by default. request_slowlog_timeout defaults to 0, which means no slow log is written. Without it, you can see that workers are busy but not which code path is blocking them. Set request_slowlog_timeout (5 seconds is a reasonable starting point) and configure the slowlog path. The stack traces tell you whether workers are stuck on a database query, an external API call, a session lock, or a filesystem stall.

Worker deaths are logged, not surfaced on the status page. Monitor the FPM error log for exited on signal lines. Any SIGSEGV or SIGBUS indicates a crash, typically from a buggy extension or opcache corruption.

Per-worker RSS is inflated by shared opcache pages. Workers are forked from the master and share read-only memory including the opcache segment. The naive sum of all worker RSS overestimates actual usage by 30 to 50 percent. For capacity math, use PSS from /proc/[pid]/smaps_rollup or smem. A 60 MB RSS worker might have a PSS of 35 MB.

If pm.max_requests is 0 (the default in many distributions), workers never recycle. This enables every memory leak death spiral. Set it to 500 or 1000. The cost is negligible (one fork every few hundred requests), and it provides a circuit breaker against unbounded growth from application code, extensions, or the runtime.

Accepted connections is a counter, not a rate. It resets to zero on every pool restart. Your monitoring must compute rate from deltas and handle counter resets. A drop to zero followed by a rapid increase from a low number means the pool was restarted.

Active processes includes workers blocked on I/O. A worker waiting on a database query or external API call is “active” from FPM’s perspective even though it uses no CPU. This is why PHP-FPM can saturate with low CPU. If you see active processes at max_children with low CPU, workers are blocked on a slow dependency, not doing compute work.

Level 3: mature

These signals provide leading indicators and composite pattern detection. They let you catch incidents minutes before users do and identify which endpoint or dependency is causing the problem.

Signal	What it tells you	Warning sign
Per-worker request duration	Latency distribution across workers	Multiple workers exceeding 10x the median
Per-worker request URI / script	Which endpoint is consuming workers	A single URI dominating active workers
Worker age distribution	Recycling health, stuck workers	Workers far older than expected with max_requests set
Kernel ListenOverflows / ListenDrops	Connections dropped at the kernel level	Counter increasing while FPM shows queue at max
OPcache wasted memory and oom_restarts	Cache fragmentation and emergency clears	wasted_memory above 30% of total, oom_restarts above 0
Per-pool monitoring	Independent pool health	One pool saturated while others are idle
Composite pattern detection	Correlated failure modes	active = max_children AND listen queue greater than 0 for more than 60 seconds

The FPM status page cannot see dropped connections. When the listen backlog overflows, the kernel drops connections before FPM sees them. FPM’s listen queue will show it at maximum, but it will not tell you how many connections were refused. The only way to detect this is kernel-level monitoring: TcpExtListenOverflows and TcpExtListenDrops in /proc/net/netstat, or ss Recv-Q on the listening socket.

Per-worker request duration is in microseconds, not milliseconds. A value of 1000000 is 1 second. Many operators misread this by three orders of magnitude. For idle workers, the field shows the duration of the last completed request, not the current state. Do not confuse an idle worker showing an old slow duration with a worker that is currently stuck.

Composite pattern detection is where monitoring becomes incident prevention. The three signals that confirm worker exhaustion are: active processes at max_children, listen queue greater than zero, and web server 502s appearing. Any one alone is ambiguous. All three together confirm the failure mode. Alerting on the composite condition reduces noise because transient spikes in a single signal do not fire.

OPcache thrash is invisible to the FPM status page. When opcache shared memory fills, PHP evicts cached scripts and recompiles them on the next request. This causes uniform CPU spikes and latency increases across all workers simultaneously. The status page shows everything normal except high CPU. Monitor opcache separately via opcache_get_status(). Track memory_usage.free_memory, memory_usage.wasted_memory, and statistics.oom_restarts. A healthy opcache has hit rate above 99% and zero oom_restarts.

Level 4: expert

Deep signals that experienced operators add after recurring incidents. They catch capacity erosion, timeout mismatches, and silent serialization that cause incidents without obvious symptoms.

Signal	What it tells you	Warning sign
Shared vs private memory (PSS)	Accurate capacity math	RSS overestimates by 30-50%, leading to under-provisioned pools
Phantom workers	Workers processing abandoned requests	Workers still running after nginx timed out and disconnected
Fork latency	Scaling responsiveness in dynamic/ondemand mode	Workers not spawning fast enough during traffic bursts
Session lock contention	Serialized requests per user	Slow log showing blocking at session_start()
request_terminate_timeout kills	Workers hitting the hard timeout	Any occurrence means something is hung, not just slow
cgroup memory (containers)	Container-level OOM	memory.events.oom_kill increasing

Measure fork latency by correlating connection-arrival time, the first worker-start log line, and first-response latency during a burst.

Phantom workers happen when nginx and FPM timeouts disagree. If nginx’s fastcgi_read_timeout is shorter than FPM’s request_terminate_timeout, nginx gives up and returns 504 to the user. But the FPM worker continues processing, delivering a response nobody will receive. These phantom workers occupy a slot doing useless work. The reverse mismatch is equally bad: if FPM kills the worker mid-response, nginx sees a broken connection and returns 502. Coordinate timeouts across the entire request path.

Session lock contention looks like capacity exhaustion but is not. With file-based sessions, concurrent requests from the same user serialize on an exclusive flock (LOCK_EX) acquired at session_start(). AJAX-heavy pages or parallel API calls from the same session block each other completely. The slow log will show workers stuck at session_start(). The fix is calling session_write_close() early in the request, or switching to Redis or Memcached session handlers with different locking semantics.

In containers, the relevant memory limit is the cgroup limit, not host memory. FPM workers do not know about cgroup limits. They allocate until the cgroup OOM killer strikes, which can kill the master process with no warning in FPM logs. On cgroup v2, monitor memory.current, memory.max, and memory.events.oom_kill. On cgroup v1, monitor memory.usage_in_bytes and memory.limit_in_bytes; memory.oom_control reports under_oom, but OOM-kill counts require correlating kernel logs.

Configuration that makes these signals work

Three pool configuration settings determine whether the signals above produce useful data. If any are at defaults, higher-level signals will not fire or will fire too late.

request_slowlog_timeout must be set (default is 0, disabled). Without it, the slow log stays empty and you lose the most diagnostic signal in FPM. Start with 5 seconds.
pm.max_requests must be set (default is 0, unlimited). Without it, workers never recycle and memory leaks accumulate indefinitely. Set to 500 or 1000.
request_terminate_timeout must be set (default is 0, disabled). Without it, a single stuck request permanently removes a worker from the pool. Set to 30 or 60 seconds, coordinated with your web server’s fastcgi_read_timeout.

How Netdata helps

Netdata’s PHP-FPM collector polls the status page and ping endpoint at per-second resolution. Saturation events unfold in seconds, so sub-minute polling intervals will miss transient queue buildups entirely.

Per-second listen queue polling catches queue spikes that 10 or 15 second intervals miss. The listen queue is a point-in-time snapshot, not an average. Between two slow polls, an entire saturation event can occur and resolve invisibly.
Correlating active processes, listen queue, and web server 502 rate in a single view confirms worker exhaustion without guessing. The three-signal composite is the fastest path from “something is slow” to “the pool is saturated.”
Per-worker RSS tracking over time detects memory leaks before they become OOM events. Historical RSS per worker makes the growth trend visible even when the absolute value looks acceptable.
OPcache hit rate and memory saturation appear alongside FPM metrics, so opcache thrash is visible as a correlated signal rather than a separate investigation.
Accepted connection rate with counter-reset handling avoids false spikes and negative rates across reloads, which reset the counter to zero.