CPU Frequency - MSR - core

What it does#

This metric provider measures the actual CPU frequency for every core on Intel CPUs by reading the hardware APERF and MPERF performance counters via the Linux MSR (Model Specific Register) interface.

Classname#

• CpuFrequencyMsrCoreProvider

Metric Name#

• cpu_frequency_msr_core

Input Parameters#

• args
  • -i: interval in milliseconds
  • -f: base CPU frequency in GHz (default: 2.4)
  • -c: check/test mode — validates that MSR counters are incrementing and then exits

By default the measurement interval is 1000 ms.

./metric-provider-binary -i 100 -f 2.4

Output#

This metric provider prints to Stdout a continuous stream of data. The format of the data is as follows:

TIMESTAMP READING CORE

Where:

• TIMESTAMP: Unix timestamp, in microseconds
• READING: The current effective frequency of the core in Hz
• CORE: The logical CPU index as reported by the kernel

Any errors are printed to Stderr.

How it works#

The provider is a compiled C binary that uses the x86 APERF and MPERF hardware counters to compute the effective CPU frequency per core.

• APERF (Actual Performance register, MSR 0xE8) increments at the actual clock rate
• MPERF (Maximum Performance register, MSR 0xE7) increments at the base (nominal) clock rate

For each sampling interval the provider reads both counter deltas and derives the effective frequency:

freq_hz = base_ghz * (APERF_delta / MPERF_delta) * 1e9

This gives the true average clock speed across the interval, including the effect of turbo boost and frequency throttling, rather than the OS governor’s requested frequency.

Core discovery is performed at startup by enumerating /sys/devices/system/cpu/cpuX/topology/core_id entries. The MSRs are then accessed via /dev/cpu/<n>/msr.

Because the binary needs to open /dev/cpu/*/msr (which is restricted to root), the compiled binary is installed with the setuid-root bit set.

Caveats#

• The -f base frequency must match the nominal (non-turbo) base clock of the CPU being measured. An incorrect value will scale all reported frequencies proportionally.
• If you have very many cores you will generate a lot of data which is tricky to interpret, as Linux constantly migrates processes between cores and measurements are not directly comparable core-to-core.
• For most users the per-core detail will be noise rather than actionable data. We recommend looking at the aggregate or only enabling this provider when debugging frequency-related behaviour.
• This provider only works on Intel CPUs. The APERF/MPERF MSRs are Intel-specific and are not available on AMD or ARM processors.
• It cannot be used on most VMs or in containers where MSR access is blocked.

Troubleshooting#

The provider requires read access to /dev/cpu/*/msr. Common failure modes:

• open msr: Permission denied — the setuid bit is not set on the binary. Re-run make from the provider directory (requires sudo).
• CPU N no MSR support — the msr kernel module is not loaded. Run sudo modprobe msr.
• MSR test failed (no counter progression) — the APERF/MPERF counters are not incrementing, which typically indicates a VM or container environment that does not expose hardware counters.
• On VMs and many cloud instances MSR access is not available. Use a different frequency provider in those environments.