Measure a Linux Command with perf stat and perf record

You will measure a command's counters with perf stat, save a sampling profile with perf record, and inspect that profile 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. Do not begin with a production service: a profile can contain command names, paths and symbol information that you may not want to disclose.

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 rather than as 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 not present. That is a prerequisite failure, not a measurement result. Install the matching package through your normal change process, then repeat this step. This guide does not install packages or alter the host.

2. List events without starting a workload

Events are the counters or trace sources that perf can request. The available names depend on the CPU, kernel and permissions, so inspect them on the machine where 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 can differ from this shortened example. Do not assume that an event shown in a guide exists on your CPU. The manual documents --no-desc as the option that 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 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

The numbers and formatting vary with the CPU, kernel and scheduler. The useful result is a counter line for each requested event and a time-elapsed line. A very short command can produce noisy ratios, so measure the real workload or run a representative test repeatedly.

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

If perf reports that it cannot open a performance event, check the error before reaching for sudo. A restrictive /proc/sys/kernel/perf_event_paranoid setting, a virtual machine, a container, or an unavailable hardware event can all be relevant. Ask the system owner before changing that setting. Running as root may bypass one permission boundary, but it does not make an unsupported event meaningful.

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 above is illustrative because mktemp chooses 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
  ...%    ...      ...             ...

The exact 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 can leave entries unresolved; 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 printed by your shell:

$ rm -rf -- "$workdir"

This deletion is irreversible. Check the value first with printf '%s\n' "$workdir", and do not substitute a broad directory or a manually typed path. If the profile is evidence, archive it securely instead of deleting it.

6. Avoid misleading comparisons

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

If you need system-wide data, obtain 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.