$ guides / php-fpm / php-fpm-opcache-cold-start ▌

Operations Guides

PHP-FPM OPcache cold start: the CPU stampede after a restart or deploy

After a PHP-FPM restart, deploy, or graceful reload, CPU climbs, latency rises, and throughput drops for the first few minutes. The OPcache shared memory segment is empty, so every worker compiles PHP source from disk before it can execute. Under enough traffic, those slow compiles tie up workers long enough to cascade into pool exhaustion, listen queue growth, and 502 or 504 errors at the edge.

This is expected behavior after any restart. It becomes an incident when a deploy hits every instance at once, when traffic is high during the window, or when monitoring fires on the CPU spike before the cache has had time to warm.

The diagnostic signature is high CPU with low throughput. Normal traffic saturation shows high CPU with throughput capped by worker count. Cold start shows CPU pinned on compilation while accepted connections stay modest and per-request durations are uniformly elevated across every endpoint, not concentrated on one slow path.

What this means

When PHP-FPM starts, the master forks workers and each worker gets a fresh PHP runtime. The OPcache segment is a single mmap(MAP_SHARED) region shared by all workers in a pool. After a restart, that segment is empty. The first request that touches a given script triggers a full parse, compile, and cache cycle before execution. Each compile costs CPU and adds latency to that request.

The compounding problem is the one-request-per-worker model. A request that normally takes 50 milliseconds might take 500 milliseconds during cold start because most of that time is spent in the compiler. Under even moderate traffic, workers stay busy longer, idle count drops, and the pool edges toward pm.max_children. If the listen queue starts building, you are in the worker exhaustion cascade even though the application code is fine.

The warmup window depends on codebase size and traffic pattern. It typically takes 5 to 30 minutes. Larger frameworks with deep autoload trees take longer because more unique scripts need their first compile. A site with low traffic takes longer in wall-clock terms because each script needs at least one hit to be cached.

The same pattern appears in ondemand mode after the idle timeout kills all workers. When traffic returns, the pool forks fresh workers with cold caches. The first few requests pay fork latency plus compile latency, which looks like a small cold start on every burst.

flowchart TD
    A[Restart / deploy / ondemand idle] --> B[OPcache shared memory empty]
    B --> C[Every request compiles PHP from source]
    C --> D[CPU pinned, latency high on all endpoints]
    D --> E{Traffic high during window?}
    E -- Yes --> F[Slow compiles hold workers longer]
    F --> G[Active at max_children, listen queue builds]
    G --> H[502 / 504 at edge]
    E -- No --> I[Cache warms in 5-30 min, hit rate climbs]

Common causes

Cause	What it looks like	First thing to check
All instances restarted at once	CPU spikes across the fleet at the same timestamp, hit rate near 0 percent everywhere	Deploy timestamp versus CPU spike timestamp
Deploy during peak traffic	Warmup window overlaps normal peak, listen queue builds, 5xx at edge	Web server access log around deploy time
`opcache.validate_timestamps = 1` left in production	Hit rate never stabilizes, CPU stays elevated, file stats dominate	`php -i \| grep validate_timestamps`
`ondemand` mode after idle	Brief latency spike when traffic returns, zero workers before the burst	Pool config `pm = ondemand`, idle count
`opcache_reset()` in deploy hook	Same signature as a full restart, hit rate drops to near 0	Deploy script for reset calls

Quick checks

# OPcache hit rate and miss counters (requires a web-accessible script calling opcache_get_status)
curl -s http://127.0.0.1/opcache-status.php | python3 -c "
import sys,json; s=json.load(sys.stdin)['opcache_statistics']
print(f\"Hits: {s['hits']}, Misses: {s['misses']}, Hit rate: {s['opcache_hit_rate']:.1f}%\")"

# OPcache memory state and OOM restart counter
curl -s http://127.0.0.1/opcache-status.php | python3 -c "
import sys,json; d=json.load(sys.stdin)
m=d['memory_usage']; s=d['opcache_statistics']
print(f\"Used: {m['used_memory']/1048576:.0f}MB, Free: {m['free_memory']/1048576:.0f}MB, OOM restarts: {s['oom_restarts']}\")"

# Pool saturation signals
curl -s http://127.0.0.1/fpm-status | grep -E "active|idle|listen queue|max children"

# Verify opcache settings via CLI SAPI (FPM may use a separate php.ini)
php -i 2>/dev/null | grep -E "opcache.validate_timestamps|opcache.revalidate_freq"

# Confirm master process start time against the CPU spike
ps -eo pid,lstart,cmd | grep '[p]hp-fpm: master'

# Confirm php-fpm workers are the CPU source
top -b -n1 -c | grep php-fpm | head

The php -i command reflects CLI SAPI settings. On distributions that ship separate ini files for CLI and FPM (Debian, Ubuntu), check the FPM ini directly or add ini_get('opcache.validate_timestamps') to your OPcache status script to see what FPM is actually using.

How to diagnose it

Confirm timing. Compare the master process start time against the CPU spike. If they line up within a few minutes, you are almost certainly in cold start.
Pull OPcache statistics. Hit rate near 0 percent with misses climbing confirms a cold cache. A high miss rate hours after restart means a different problem, such as thrashing, validate_timestamps, or a too-small cache.
Check whether the cascade has started. Look at active processes relative to pm.max_children, listen queue depth, and the web server 5xx rate. If active is near max_children and the queue is growing, the cold start has tipped into worker exhaustion.
Verify production settings. opcache.validate_timestamps should be 0 in production. If it is 1, every request stats the file and may invalidate the cache on any timestamp change, extending the warmup indefinitely. Remember to check the FPM SAPI, not just CLI.
If using ondemand, confirm the idle pattern. Zero workers followed by a burst produces a small cold start on every wake. This is by design but worth distinguishing from a deploy-related cold start.

Metrics and signals to monitor

Signal	Why it matters	Warning sign
OPcache hit rate	Direct measure of warmup progress	Near 0 percent after restart is expected. Still below 95 percent after 30 minutes of traffic is not.
OPcache misses per second	Cumulative hit rate hides current state. The miss rate shows whether compiles are still happening.	Sustained nonzero miss rate on a supposedly warm cache.
OPcache memory usage	A too-small cache causes evictions and oom_restarts, which reproduce cold start under load	free_memory below 10 percent, oom_restarts greater than 0
CPU usage	Compilation is CPU-heavy. High CPU with low throughput is the cold start signature	CPU pinned in the first minutes after restart is expected. Suppress alerts here.
Active processes vs max_children	Cold start can tip into worker exhaustion under load	Active at max_children with listen queue growing
Listen queue depth	Earliest signal that slow compiles are exhausting the pool	Nonzero and growing during the warmup window
Per-worker request duration	Uniformly elevated durations indicate compilation overhead across all endpoints	All workers showing durations well above baseline

Fixes

Stagger the restart

The single most effective mitigation is to not restart every instance at once. Roll deploys one instance at a time, give each instance a warmup window before sending it full traffic, and only then move to the next. Behind a load balancer, take one instance out of rotation, deploy, warm, and re-add. This trades deploy time for stability and avoids the fleet-wide CPU spike.

Pre-warm critical endpoints

Before returning a freshly restarted instance to full traffic, exercise the hot paths. Hit the front controller, the most common API endpoints, and any path that loads a large subset of the autoloader. The goal is to trigger the first compile of the highest-traffic scripts so the cache is partially populated before real users arrive. A simple loop over a known list of URLs is usually enough.

Use opcache.preload (PHP 7.4 and later)

Preloading compiles and links a configured set of scripts at PHP-FPM startup, before any request is served. With a well-built preload list, the cache is already warm when the first request arrives.

Two operational gotchas are worth flagging. First, opcache.preload and opcache.preload_user are PHP_INI_SYSTEM directives. They must be set in php.ini or the global FPM config, not via php_value in a pool config file. Second, the benefit for many applications is marginal after warmup. Preloading removes per-request autoload overhead, but once OPcache is warm the steady-state gain is small and highly application-dependent. Benchmark before committing to a preload list.

Consider opcache.file_cache (PHP 7 and later)

The file-based secondary cache stores compiled opcodes on disk. When shared memory is cold after a restart, workers read compiled opcodes from disk instead of recompiling from source. You can pre-warm the file cache during the build by iterating PHP files and calling opcache_compile_file(), then ship the populated cache in the image. On PHP 8.5, opcache.file_cache_read_only exists and defaults to 0; it is an INI_SYSTEM directive. Set it to 1 for an immutable image cache.

Do not call opcache_reset() in the deploy hook

Clearing the cache on every deploy reproduces the cold start on purpose. With opcache.validate_timestamps = 0, a normal FPM restart or graceful reload (SIGUSR2) swaps the cache as a side effect of restarting workers. If you need to clear stale bytecode, prefer the restart over a programmatic reset, and only when the deploy actually changed files.

Suppress CPU alerts during the known window

If alerting fires on CPU in the first 5 to 10 minutes after a known restart, you will page on every deploy. Suppress CPU alerts for the warmup window, or alert on a composite signal: CPU high AND OPcache hit rate still below threshold AND master uptime under N minutes.

Prevention

Run opcache.validate_timestamps = 0 in production. Let restarts and reloads be the cache invalidation event, not every file stat.
Size opcache.memory_consumption and opcache.max_accelerated_files for the full codebase. A too-small cache causes oom_restarts and evictions, which reproduce the cold start signature under load.
Adopt rolling deploys as the default. Cold start is a per-instance problem. It only becomes an incident when it happens everywhere at once.
Maintain a pre-warm script in the deploy pipeline. Run it before an instance goes back into rotation.
If you run ondemand pools, accept the small cold start on burst as a design tradeoff. Switch to dynamic with adequate pm.min_spare_servers for latency-sensitive workloads.
Rehearse the deploy. The first time you find out your warmup window is 20 minutes should not be during a production incident.

How Netdata helps

The PHP-FPM collector surfaces pool metrics (active processes, idle processes, listen queue depth, max children reached) at per-second resolution. During a cold start, the useful correlations are:

Pool saturation vs CPU: Active processes climbing toward max_children while CPU is pinned but throughput is low confirms cold start rather than genuine traffic overload.
Listen queue growth: The queue depth rising during the warmup window is the earliest signal that slow compiles are exhausting the pool.
Edge 5xx rate: Correlating 502/504 responses with FPM pool state and a recent master process restart confirms the cold-start cascade without guessing.

If OPcache metrics are available through your monitoring setup, the hit-rate curve and miss-rate delta are the direct measures of warmup progress. A flat-lining hit rate with sustained misses after the warmup window points to validate_timestamps thrashing or a too-small cache, not cold start.