PHP-FPM in containers: cgroup limits and the silent OOM kill

The container restarts, or the PHP-FPM error log fills with child N exited on signal 9 (SIGKILL) entries, but dmesg shows no global OOM event. The host has plenty of free RAM. The PHP memory_limit is set well below the kill threshold. None of the obvious explanations fit.

PHP-FPM has no awareness of cgroup memory limits. Workers allocate against the PHP heap (capped by memory_limit), against extension memory (Imagick, libxml, glibc arenas), and against page cache for mmap’d files. None of those allocations consult memory.max in the cgroup. When the cgroup as a whole crosses its limit, the kernel cgroup OOM killer fires a SIGKILL at a process inside the cgroup. Whether the victim is a single worker or the master process determines whether you see a silent kill or a container restart.

The classic operator confusion: I set memory_limit = 256M and I have 10 workers, so why is the 2GB container dying? The answer is that memory_limit is per-request on the PHP allocator only. It is not an aggregate cap, and it does not cover extension or libc memory. The cgroup limit is the only aggregate cap, and PHP-FPM does not consult it.

What this means

Inside a container, the boundary that matters is memory.max on the PHP-FPM cgroup, not host free RAM. The cgroup v2 OOM killer is localized: it shoots a process inside the cgroup and does not produce the familiar Out of memory: Kill process line in host dmesg. The signature is in two places instead.

First, the PHP-FPM error log: WARNING: [pool www] child N exited on signal 9 (SIGKILL) after X seconds from start. The signal number is the giveaway. SIGKILL (9) on a worker, with no segfault context, points at the OOM killer rather than a crash in PHP code or an extension.

Second, the cgroup’s own event counter. /sys/fs/cgroup/memory.events shows a non-zero oom_kill count, and oom increments on the kill path. This is the authoritative signal that the kernel killed something inside this cgroup for memory reasons, regardless of what the host log says.

The silent vs. visible distinction comes down to victim selection. If the cgroup OOM killer picks a child worker, the master respawns it and the container survives. Pod health checks pass. The only trail is in the FPM log plus the memory.events counter. If the victim is the master process, and the master is PID 1 in the container (the typical container layout), the container exits. The orchestrator records OOMKilled: true in Docker or a pod restart with reason OOMKilled in Kubernetes, and monitoring of the FPM process itself is replaced by monitoring of the pod lifecycle.

Kubernetes 1.32 added singleProcessOOMKill as a kubelet configuration option, not a feature gate. Its default preserves the cgroup v2 memory.oom.group group-kill behavior; setting it to true opts a node into single-process kills.

On Kubernetes 1.28+ with cgroup v2, memory.oom.group is enabled by default on the container cgroup. That changes the math: when any process in the container trips the limit, the kernel kills the entire cgroup (the whole container), not just the offending process. The kill becomes visible to kubelet as a pod restart. Older clusters, or singleProcessOOMKill=true, revert to the per-process behavior, which is where the invisible-kill pattern shows up.

flowchart TD
    A[Worker allocates beyond PHP memory_limit] --> B[Total cgroup RSS crosses memory.max]
    B --> C{memory.oom.group enabled?}
    C -->|disabled or singleProcessOOMKill| D[Kernel picks one process]
    D --> E{Victim}
    E -->|Child worker| F[SIGKILL, FPM logs signal 9, container survives]
    E -->|Master or PID 1| G[Container exits, OOMKilled true]
    C -->|enabled, default on K8s 1.28+| G
    F --> H[Silent: only trail is FPM log plus memory.events]
    G --> I[Visible: orchestrator records restart]

Common causes

Quick checks

# Read the cgroup memory limit and current usage (cgroup v2)
cat /sys/fs/cgroup/memory.max
cat /sys/fs/cgroup/memory.current

# OOM event counters. Non-zero oom_kill confirms cgroup OOM activity.
cat /sys/fs/cgroup/memory.events

# Break down anonymous versus file-backed memory inside the cgroup
grep -E '^(anon|file|slab|sock)' /sys/fs/cgroup/memory.stat

# PHP-FPM worker SIGKILL pattern in the error log
grep "exited on signal 9" /var/log/php-fpm/error.log | tail -20

# Confirm no global host OOM. The absence here is the point.
dmesg -T | grep -i "out of memory" | tail

# Average and max worker RSS. Note the shared-page overcount.
ps -eo pid,rss,cmd | grep '[p]hp-fpm' | grep -v master | \
  awk '{sum+=$2; n++; if($2>max) max=$2} END {printf "n=%d avg=%d KB max=%d KB\n", n, sum/n, max}'

# Accurate per-worker memory using PSS, which accounts for shared opcache pages
smem -P php-fpm -c 'pid pss rss' -s pss 2>/dev/null | tail -20

# Docker: confirm the container was OOM-killed at the PID 1 level
docker inspect --format '{{.State.OOMKilled}}' <container>

For cgroup v1 hosts, the equivalent files are memory.limit_in_bytes, memory.usage_in_bytes, and memory.failcnt inside the cgroup directory. Kubernetes 1.31 moved cgroup v1 support to maintenance mode; it did not drop it there. Modern Kubernetes and Docker defaults are cgroup v2.

How to diagnose it

1. Confirm the kill is cgroup-local. A non-zero oom_kill in /sys/fs/cgroup/memory.events paired with no matching entry in host dmesg confirms a localized cgroup OOM, not a host-level event. This single check eliminates most of the wrong rabbit holes.

2. Confirm the kill victim. If only the FPM error log shows signal 9 entries and the container is still running, the kernel killed workers and the master survived. If the container restarted and docker inspect shows OOMKilled: true, the master (likely PID 1) was the victim. On Kubernetes, check pod restart counts and the pod’s last termination reason.

3. Establish the actual per-worker footprint. Use PSS from smem or /proc/<pid>/smaps_rollup, not raw RSS. RSS double-counts the opcache shared segment across every worker, so the naive sum of RSS overstates true memory by a meaningful margin. PSS divides shared pages by the number of sharing processes and gives a defensible number to multiply by pm.max_children.

4. Compute worst-case cgroup footprint. Compare (peak avg PSS * max_children) + opcache_segment + master_overhead + headroom_for_bursts against memory.max. The opcache segment is counted once physically but is page-cache backed; account for it explicitly. If the math approaches 90% of memory.max, the next large request tips the cgroup over.

5. Look at memory.stat to see what is growing. If anon is climbing per worker over time, that is a leak in PHP code or an extension. If file is high and growing, that is page cache, often from ImageMagick temp files or large PHP file reads. The fix differs.

6. Inspect the FPM error log for the cadence of signal 9 entries. A slow steady trickle suggests leak-driven pressure. A burst at a specific time suggests a specific request pattern (image upload, export, report generation). Cross-reference the slow log if request_slowlog_timeout is set.

Metrics and signals to monitor

Fixes

Size pm.max_children against the cgroup, not the host

Use PSS, not RSS, and leave headroom:

max_children = floor((memory.max - opcache_segment - master_overhead - headroom) / peak_avg_pss)

Reserve at least 20-30% of memory.max for bursts, page cache, and the glibc allocator’s habit of holding freed memory. If the resulting max_children is too small to handle traffic, the answer is to raise memory.max or reduce per-worker footprint, not to disable the safety margin.

Set pm.max_requests to a finite value

With pm.max_requests = 0 (the default in many distros), workers never recycle and any leak in PHP code or an extension accumulates without bound. Set pm.max_requests between 500 and 1000. The recycling cost is one fork per N requests and is negligible. This is the single most common PHP-FPM misconfiguration, and the most common root cause of slow-motion OOM in containers.

Cap extension threading

ImageMagick and similar extensions spawn OpenMP threads per worker. Each thread allocates its own glibc malloc arena, which can balloon RSS by hundreds of MB per worker on a single large image. Set these in the FPM pool config:

env[OMP_NUM_THREADS] = 1
env[MAGICK_THREAD_LIMIT] = 1
env[MALLOC_ARENA_MAX] = 2

MALLOC_ARENA_MAX = 2 constrains glibc to a small number of arenas per worker, which dramatically reduces RSS growth on multi-threaded extensions at a small latency cost.

Acknowledge the memory_limit non-cap

memory_limit is per-request on the PHP allocator. It does not bound extension memory, glibc arena memory, page cache, or cumulative allocations across many requests in a long-lived worker. Setting memory_limit = 256M does not stop 10 workers from consuming 2.5GB at the cgroup level. Stop treating it as an aggregate cap. A pm.max_memory feature request exists as php/php-src issue 17661 and remains open as of August 2026.

Add the slow log if missing

Without request_slowlog_timeout set, you can see that workers are dying but not which request path is causing the memory pressure. Set request_slowlog_timeout = 5s (or higher for slow endpoints) on every production pool. The slow log captures stack traces that point directly at the leaking or ballooning code path.

Prevention

• Check the cgroup math at deploy time, not at 3 a.m. Treat max_children * peak PSS + overhead against memory.max as a CI check, not an afterthought.
• Monitor memory.events.oom_kill as a first-class signal. Any non-zero value during normal traffic is a problem the kernel already solved for you with a SIGKILL. The next victim may be the master.
• Use PSS for capacity planning, RSS for trend detection. RSS is fine for spotting leaks; it overcounts for sizing.
• Treat container restarts with OOMKilled: true as a PHP-FPM signal, not an infrastructure signal. The orchestrator is reporting a downstream consequence of cgroup pressure caused by FPM workers.
• Resist raising memory_limit as a fix. It does not bound what is actually killing you. Lower max_children, raise memory.max, or fix the leak.

How Netdata helps

The failure is invisible from inside PHP-FPM. The signals that matter live at the cgroup and kernel layers, and per-second collection matters when a single large request tips the cgroup over in seconds.

• cgroup v2 memory collectors surface memory.current, memory.max, and memory.events (oom, oom_kill) per container, so the cgroup-local kill shows up even when host dmesg is empty.
• Per-process RSS tracking for FPM workers lets you watch the leak trend between recycles and spot which workers balloon on which requests.
• The PHP-FPM collector exposes active and idle workers, listen queue, max-children-reached, and the slow-request counter. Correlating these with memory.current shows whether throughput is dropping because of pool saturation or because workers are being shot.
• ML anomaly detection on memory.current and per-worker RSS flags the slow climb that precedes a kill, hours before the kernel takes action.
• Container restart events and orchestrator state close the loop when the master is the kill victim and the FPM process itself is gone.
• Composite dashboards let you put cgroup memory, worker RSS, FPM status, and orchestrator restarts on one screen, which is where the silent OOM actually becomes legible.

Related guides

• PHP-FPM 504 Gateway Timeout: requests accepted but never finishing in time
• PHP-FPM active processes near max_children: reading pool utilization
• How PHP-FPM actually works in production: a mental model for operators
• PHP-FPM idle processes at zero: no burst headroom left
• PHP-FPM listen queue growing: the earliest signal of saturation
• PHP-FPM “server reached pm.max_children setting (N), consider raising it”
• PHP-FPM memory leak: per-worker RSS climbing until the box runs out
• PHP-FPM monitoring checklist: the signals every production pool needs
• PHP-FPM monitoring maturity model: from survival to expert
• PHP-FPM workers OOM-killed: “child N exited on signal 9 (SIGKILL)” and the memory cliff
• PHP-FPM request duration climbing: spotting stuck and outlier workers
• PHP-FPM request_terminate_timeout: stopping stuck requests from eroding the pool