Measure a Command with perf stat and perf record

perf stat counts hardware and kernel events for a command while it runs, and perf record saves samples you can inspect later with perf report. The examples use the installed perf wrapper on this machine, from linux-tools-common 6.8.0-142.142.

Allow about fifteen minutes for a first run, plus time to repeat the workload if it is short or variable. You need a shell, a command you can run repeatedly, and enough permission for the kernel's performance-event policy. These examples only observe a process; they do not change the program or system configuration.

1. Check that perf matches the running kernel

Start with read-only checks. This matters because perf is often installed as a kernel-specific tool, not one universal binary:

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

On this host the wrapper exits after that warning because the matching linux-tools-6.8.0-139-generic package is missing. That is a prerequisite failure, not a measurement result. Install the matching package through your normal change process, then repeat this step.

2. List events without starting a workload

Events are the counters or trace sources perf can request. Available names depend on the CPU, kernel and permissions, so check them on the machine you will measure:

$ perf list --no-desc | sed -n '1,40p'
  branch-instructions OR branches
  cache-misses
  cache-references
  cycles
  instructions
  ...

The output is hardware-specific and will differ from this shortened example. Do not assume an event from a guide exists on your CPU. --no-desc just suppresses descriptions; keep the full event name when selecting one with -e.

3. Measure one command with perf stat

Run a small, repeatable command first. The -- separates perf's own options from the command's arguments:

$ perf stat -e cycles,instructions -- /usr/bin/sleep 1

 Performance counter stats for '/usr/bin/sleep 1':

       ...      cycles
       ...      instructions

       ...      seconds time elapsed

Numbers and formatting vary with CPU, kernel and scheduler. What you want is a counter line for each requested event and a time-elapsed line. A very short command produces noisy ratios, so measure the real workload or repeat a representative test.

Without -e, perf selects its default statistics set. Use an explicit event list when comparing runs, since defaults and event availability differ between machines. The measured command itself stays unmodified; perf reports its counters after it exits.

4. Record a profile for a longer workload

perf stat gives aggregate counts. Use perf record when you need samples showing where time was spent. Save the output in a dedicated directory so an old profile cannot be mistaken for the new run:

$ workdir="$(mktemp -d)"
$ perf record -o "$workdir/perf.data" -- /path/to/your-command --safe-test-arguments
$ test -s "$workdir/perf.data" && echo "profile written: $workdir/perf.data"
profile written: /tmp/tmp.XXXXXXXX/perf.data

Replace the placeholder command and arguments with a real test workload. The output file is binary data: do not paste it into a terminal or commit it to a repository. The sample path is illustrative, since mktemp picks a different directory each time.

5. Read the profile with perf report

Inspect the file explicitly rather than relying on the default perf.data in your current directory:

$ perf report -i "$workdir/perf.data"
Samples: ...  of event 'cycles'
Overhead  Command  Shared Object  Symbol
  ...%    ...      ...             ...

Columns depend on the recorded events and whether debug symbols are available. A high overhead percentage points to sampled execution, not automatically to a bug. Confirm the workload, event, compiler build and machine before comparing two reports; missing symbols leave entries unresolved, so install or expose debug information only under your normal package and data-handling rules.

When the report is no longer needed, remove the temporary directory with the exact path your shell printed:

$ rm -rf -- "$workdir"

Avoid misleading comparisons

• Keep everything else constant. Command line, input, build, CPU workload and selected events should not change between runs.
• Repeat short tests. One run can be dominated by startup, background activity or CPU frequency changes.
• Record the context. Note whether the command ran in a virtual machine, container or system-wide session; those change what the kernel permits and what the counters mean.
• Do not use perf record -a casually. -a requests system-wide collection, which can capture unrelated processes and sensitive activity.

If you genuinely need system-wide data, get explicit approval, define a short collection window, choose an output location with suitable permissions, and remove or protect the resulting file when the investigation ends.