open-standards/jcp/tools/counter-resolution

What a counter can actually resolve

Two harnesses behind the numbers jcp-energy declares. Both are the evidence for a constant in the crate; neither is a test of the crate.

counter_resolution.py — the per-process CPU counter's update period

ri_energy_nj is the only source in the survey that attributes energy to a principal rather than to silicon, so whether it may grade a span decides whether Apple silicon has any process-attributed reading at all.

Burns this thread's CPU for a fixed interval, samples the counter 60 times per interval, and reports the fraction of intervals in which it advanced — the crate's own liveness criterion is 80%.

Measured on an M5 Max, macOS 27:

interval	advanced	median step	clears 80%
10 µs	0%	—	no
50 µs	0%	—	no
100 µs	2%	20.4 mJ	no
500 µs	5%	21.1 mJ	no
1 ms	35%	2.8 mJ	no
2 ms	63%	4.9 mJ	no
5 ms	87%	9.6 mJ	yes
10 ms	100%	19.0 mJ	yes
50 ms	100%	92.9 mJ	yes

The crate declares 10 ms, not the 5 ms where it first clears the criterion: over-declaring a period refuses spans that would have been fine, while under-declaring grades spans that were not, and at a ceiling only the second error is dangerous.

Note the shape below 1 ms. The counter does not lag smoothly — on the few intervals where it advanced at all, the median step was ~20 mJ, two orders above the 1 ms step. It accrues in lumps, which is the same batched-refresh pathology the crate already refuses on IOReport's CPU rails. A sampler that read it every 500 µs would see nothing most of the time and a 20 mJ jump occasionally, and would report both as measurements.

This is also why a per-operation figure for an 11.85 ms decision is taken as the mean of 200 decisions over a 2.6 s span rather than as 200 counter reads.

ioreport_rails.py — which Apple rails exist and advance

Enumerates the IOReport Energy Model group unprivileged (364 rails on an M5 Max) and prints each channel's name, unit and delta. What it establishes: GPU Energy is live in nJ, every CPU Energy / MCPU* / PACC* / *_SRAM rail is frozen for an unprivileged reader, and ANE0 is the only ANE channel — no ANE Energy aggregate, no sub-rails. Units differ within one sample, so a summer that assumes one unit is wrong.

gpu_rail_period.py / gpu_rail_idle_tail.py — when the GPU rail republishes

The GPU Energy rail has no fixed period. It republishes when there is activity to report and holds its value when there is not, so the number you measure depends entirely on which condition you measure in.

Sampling every 2 ms on an M5 Max, macOS 27, the gap between actual changes:

condition	p50	p90	p95	p99	max	n
sustained MLX matmul	13.1 ms	15.0 ms	—	—	42.0 ms	435
idle, 6 s	12.7 ms	91.0 ms	—	—	992.2 ms	112
idle, 90 s	13.1 ms	30.6 ms	86.2 ms	436.2 ms	2032.8 ms	2936

Three things follow, and the third is why the long run exists.

Under sustained load the rail is tight; the long tail is an idle property. That is the opposite of the intuitive reading, and it reconciles an earlier fleet observation that put the hold at "300–600 ms under load": the GGUF decode it came from is dispatch-latency-bound with idle gaps between tokens, so it was sampling idle behaviour. 300–600 ms is about the idle p98–p99 here, consistent with having seen that region and not past it.

A declared period has to be the idle worst case. A measurer cannot guarantee the fabric stays busy, and a span landing entirely inside one hold reads zero — which a naive grader would report as a measurement of zero. jcp-energy declares 1 s for this rail on that basis.

The sample max is not a bound. The 6 s run gave a max of 992.2 ms, which sits just inside a 1 s timeout and invites the conclusion that 1 s is enough. Over 90 s the same host produced three gaps past 1000 ms — 1446, 1919 and 2033 ms — so roughly 1 idle gap in 1000 exceeds a one-second wait, and the worst was 2× it. Any code that waits a bounded time for this rail to republish should bound above ~2.5 s, or treat the timeout as a counted outcome rather than a rare surprise.