improve cpu metrics - #107
Merged
Merged
Conversation
php-fpm's %C is the percentage of a request's wall time spent on CPU, not a
duration -- see sapi/fpm/fpm/fpm_log.c, which computes it as
tms_total / fpm_scoreboard_get_tick() / cpu_duration * 100
Summing a percentage across requests therefore produces a meaningless number,
so phpfpm_request_cpu_total_sum could not be used for anything and the image
had no CPU metric suitable for capacity work.
Multiply by the request duration instead to get CPU seconds, which is additive
across requests, pools and sites:
cpu_seconds = (cpu_total / 100) * (duration_ms / 1000)
rate(phpfpm_request_cpu_seconds_sum) is then CPU cores consumed. fpm_request_end()
derives %C's denominator and %d from the same interval (both start at
proc->accepted), so the conversion is exact rather than approximate.
The duration-weighted mean percentage remains recoverable as
cpu_seconds_sum / (duration_ms_sum / 1000) * 100, which is a more correct mean
than the previous unweighted one.
Note this makes %d a prerequisite: a custom METRICS_PHP_FPM_ACCESS_LOG_FORMAT
without a duration cannot produce cpu_seconds, and will emit no CPU metric.
BREAKING CHANGE: phpfpm_request_cpu_total_{sum,count} are no longer emitted and
are replaced by phpfpm_request_cpu_seconds_{sum,count}. Series count per request
is unchanged.
…ry_bytes
php-fpm's %M reads proc.memory, which fpm_request_end() sets from
zend_memory_peak_usage(1) -- a per-request high-water mark, not an amount of
memory consumed. Summing high-water marks across requests yields a number that
never corresponded to any memory that existed, the same class of error as
summing cpu_total. Only sum/count was interpretable, and that discards the tail.
Multiply by the request duration to get the time integral, matching the
cpu_seconds treatment:
memory_byte_seconds = memory_bytes * (duration_ms / 1000)
rate(phpfpm_request_memory_byte_seconds_sum) is then the mean bytes held
concurrently by php workers, which is additive across requests, pools and sites.
The duration-weighted mean peak remains recoverable as
memory_byte_seconds_sum / (duration_ms_sum / 1000).
Two caveats worth knowing when using it:
- peak * duration overestimates the true integral, since memory ramps up
rather than sitting at peak for the whole request. The error is in the
safe direction for capacity work.
- this is request-attributable memory, not container memory. PHP's
allocator does not return memory to the OS, so a worker retains its
own high-water mark across every subsequent request until
pm.max_requests recycles it. No per-request metric can observe that;
cgroup memory accounting is the right source for container-level sizing.
BREAKING CHANGE: phpfpm_request_memory_bytes_{sum,count} are no longer emitted
and are replaced by phpfpm_request_memory_byte_seconds_{sum,count}, which has a
different unit (byte-seconds rather than bytes). Series count per request is
unchanged.
fcoelho
force-pushed
the
feature/ops-1311-improve-cpu-metrics
branch
from
August 11, 2026 11:30
d24a7c8 to
477fee3
Compare
fcoelho
marked this pull request as ready for review
August 11, 2026 12:07
chrislrobinson
approved these changes
Aug 11, 2026
MattGrundy
approved these changes
Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.