Measure CPU Frequency and Idle Time with turbostat

A CPU stuck at a low clock is either idle or throttled, and turbostat tells you which. You will finish with a repeatable command that records frequency, busy time and idle-state residency, and know when a power or temperature figure is legitimately absent, and why a very short sample can mislead you.

This guide follows turbostat from the locally installed linux-tools-common package, version 6.8.0-142.142. The installed binary is not available for the running 6.8.0-139 kernel on this machine, so the examples are checked against the installed manual rather than claimed as a live measurement. Allow about fifteen minutes. You need an x86 Linux host, a shell and root access for the normal invocation.

1. Check the installed tool and privilege boundary

Confirm which package and executable your shell would actually use first. These are ordinary read-only checks:

$ command -v turbostat
/usr/bin/turbostat
$ dpkg-query -W -f='${Package} ${Version}\n' linux-tools-common
linux-tools-common 6.8.0-142.142
$ turbostat --version
WARNING: turbostat not found for kernel 6.8.0-139

That warning means the wrapper cannot find a kernel-specific turbostat binary for the running kernel. Install the matching tools package through your normal operating-system change process before treating a measurement as successful. Do not silently substitute a binary from an unrelated build when comparing results across hosts.

On a host with a usable binary, turbostat normally requires root. Start a measurement with sudo rather than changing permissions on /dev/cpu/*/msr or granting capabilities to the executable: those alternatives change the machine's security boundary and need an explicit ownership, review and rollback plan.

2. Take a focused one-shot measurement

A command placed after turbostat is run by turbostat and measured until it exits, which makes it the clearest first test because the workload has a defined end:

$ sudo turbostat --quiet --show CPU,frequency sleep 10

Expect one measurement after the ten-second sleep. --quiet removes the hardware and kernel configuration dump. --show limits the columns, and the manual documents frequency as a column category. The system summary row is followed by rows for individual logical CPUs selected for display.

3. Read the main columns without over-interpreting them

• Avg_MHz is cycles executed divided by elapsed time, so idle time is included. It is not the clock speed while instructions were actually running.
• Busy% is the percentage of the interval spent executing instructions, also described as time in the C0 state.
• Bzy_MHz is the average clock rate while the CPU was not idle.
• TSC_MHz is the average rate of the time-stamp counter over the complete interval.

For idle behaviour, software-requested columns such as C1% and hardware residency columns such as CPU%c7 answer different questions: the former describe what Linux requested, the latter come from hardware residency counters and describe what the hardware reported. On a multi-CPU system, the summary percentage is an average, while count columns are summed.

Do not compare a single busy CPU row with the system summary as if they were the same measurement. The summary covers all CPUs even when --cpu limits which per-CPU rows are printed.

4. Discover columns before building a report

Column names and categories are easier to discover than to guess. Ask turbostat for its list:

$ sudo turbostat --list

Use the resulting names with --show or --hide. --show displays only what you name; --hide starts with the available columns and removes the ones you name. Both options can be repeated or given a comma-separated list. The categories all, topology, idle, frequency, power, sysfs and other can also be used where the installed version supports them.

A compact frequency report can therefore be written as:

$ sudo turbostat --quiet --show CPU,frequency --interval 2 --num_iterations 5

This runs five two-second intervals when no child command is supplied. Expect repeated headings and measurement rows. The default interval is five seconds, so specifying both options makes the sampling plan visible and reproducible.

5. Save output without losing the safety check

Use --out when another person needs the complete report:

$ sudo turbostat --out /tmp/turbostat-report.txt sleep 10
$ sudo sed -n '1,24p' /tmp/turbostat-report.txt

In one-shot command mode, output goes to standard error by default; periodic mode writes to standard output by default. --out makes the destination explicit in either case and avoids a common trap when redirecting a one-shot measurement.

6. Limit displayed CPUs, not the collection scope

Use --cpu when a report would be too wide:

$ sudo turbostat --quiet --cpu 0-3 --show CPU,frequency sleep 1

The accepted set can contain comma-separated values and ranges such as 1,2,8,14..17,21-44. The special values core and package print the first CPU in each core or package. This option only limits displayed per-CPU rows, turbostat still collects data for every CPU and keeps the all-system summary.

If a CPU number is offline or absent, stop and inspect the host's topology rather than editing the command until it appears to work. A partial-looking table is not proof that the requested set was meaningful.

Common traps

• Trusting a very short interval. The manual says collection is not atomic, and very short intervals, or activity preventing turbostat from running promptly on every CPU, can produce inconsistent results. Use a stable workload, repeat the measurement and record the interval, command, kernel and package version with the report.
• Expecting every power and temperature field. They are not universal: PkgWatt is package power, while CoreTmp and PkgTmp are different temperature readings. Graphics and DRAM fields are available only on relevant processor types. A dash or absent column is a hardware or driver limitation, not automatically a fault.