An AI chat service can appear slow even when its model provider is healthy. If a PHP endpoint holds a worker while waiting for an upstream generation, the web tier may exhaust capacity first. The right response is not automatically to double pm.max_children. This runbook connects queue evidence, memory measurements and user-visible latency before changing PHP-FPM settings, with a rollback plan for a production API.
Model worker occupancy before editing a configuration
Start with the transaction boundary: authentication, validation, database reads, model request, optional media generation, response streaming and final accounting. Measure how long each phase occupies a PHP-FPM child rather than treating total API duration as CPU time. A long-held synchronous network call can consume a worker while performing almost no CPU work. A queueing model therefore needs the arrival rate, the distribution of occupied time and the latency budget for a response.
The official PHP-FPM configuration manual documents static, dynamic and ondemand process managers and explains that pm.max_children caps simultaneous served requests. For an illustrative calculation, a service receiving 25 requests each second with 0.4 seconds of occupied time averages roughly ten busy workers before considering bursts or variance. That is an illustrative engineering assumption, not a production measurement or an invitation to configure exactly ten children.
Calculate a conservative memory ceiling
Measure resident memory across representative workers after they have processed both normal and heavy requests. A process with a large image-decoding library loaded may be much larger than a worker serving only JSON. Reserve headroom for the operating system, reverse proxy, monitoring agents, database connections and sudden heap peaks. Estimate a ceiling by dividing the memory budget allocated to FPM by a high-percentile observed per-worker footprint, and then test below that ceiling.
For example, if the process budget is 3 GiB and a conservative worker footprint is 110 MiB, a naive division gives about 27 workers. Neither number is a recommendation: memory sharing, fragmentation, peak allocations and other resident services can invalidate the estimate. Prefer a repeatable test with an explicit safety margin. A crash or swap storm under the proposed setting is evidence to lower concurrency or offload blocking work rather than repeatedly raising limits.
Use the FPM status page as internal telemetry
The PHP-FPM status page documentation lists accepted connections, active and idle processes, listen queue, maximum active processes, max children reached and slow requests. These reveal where work waits and whether the process limit is being hit. Collect counters over time and calculate rates from counter differences, while remembering that counters reset when a pool restarts. Correlate FPM metrics with ingress requests, database saturation and upstream response times.
Do not expose the FPM status page to the public internet. PHP’s manual explicitly warns that it reveals request and capacity details. Restrict it to a monitoring network, use authenticated access as appropriate, and avoid exporting full request URIs when they may contain identifiers. Set alerts on sustained queue delay and saturation over a window rather than a single spike. A queue can briefly grow during a planned deployment without indicating an ongoing capacity failure.
Move long jobs away from user-facing workers
An endpoint that generates a high-resolution AI video or uploads a large clip should not necessarily keep a web request open for the entire task. Separate the creation of an authorized job from asynchronous execution, and return a job ID with a meaningful state. If a task requires streaming, choose a runtime and connection strategy that have been load-tested rather than assuming conventional short-request PHP-FPM behavior applies to lengthy interactions.
Document retry behavior carefully. The client may resend a request after a timeout even if the server already created the job. An idempotency key should represent the logical action and its parameters; duplicate requests should retrieve the existing result rather than producing two billed generations. Establish cancellation and expiry states to free workers and external resources. This prevents performance work from accidentally becoming a billing or privacy problem.
Load-test contention, not just average throughput
Build scenarios with quiet traffic, a realistic morning spike, a temporary model-provider slowdown, a database lock delay and a mix of short text and longer media-related requests. Record p50, p95 and p99 response times alongside queue depth, CPU, memory, worker utilization and failed request rates. A throughput graph alone hides whether a small share of users experience severe tail latency. Fix resource starvation at its source before tuning cosmetic timeouts.
Use a stepwise test: establish a baseline, change one pool parameter, rerun identical traffic, and preserve a rollback configuration. Compare static, dynamic and ondemand policies only under measured startup and memory conditions. A pool that looks efficient during an average load may suffer cold-start delays or run out of idle processes during a burst. The operational target is predictable, user-visible service rather than maximal worker count.
Create an incident runbook and acceptance gates
The runbook should say what to check when the service returns 502 or 504 errors, where to find recent FPM restarts, whether the upstream model provider is slow and which adjustment has a known rollback. Give each alert a threshold tied to observed baseline behavior. If max children reached climbs while memory remains healthy, additional workers may help; if swapping begins, they may make failure worse. Inspect and justify instead of automating blind configuration increases.
Release gates can include zero out-of-memory events in the test, bounded queue time at the target percentile, correct idempotent retries, acceptable error rates and a restored configuration after rollback rehearsal. Log test versions, anonymized load profiles and business outcomes such as successful first chat rather than collecting unnecessary dialogue text. The final benefit is a measurable capacity decision that a second engineer can independently reproduce.