perf: Usage, Options & Common CI Errors

perf samples a program with CPU performance counters to find hot spots.

perf is the Linux profiler for CPU-bound performance work. In CI it is constrained by the perf_event_paranoid sysctl and by containers that lack the needed capability, both of which block counter access before any code even runs.

What it does

perf uses the kernel’s perf_events subsystem and CPU hardware counters to profile programs: counting events (perf stat), sampling stacks (perf record), and rendering reports (perf report). It identifies CPU hot spots, cache misses, and branch mispredictions.

Common usage

Terminal

perf stat ./app                    # summary counters
perf record -g ./app               # sample with call graphs
perf report                        # interactive report of perf.data
perf record -F 99 -g -- ./app      # sample at 99 Hz
perf stat -e cache-misses ./app    # a specific counter

Options

Subcommand / flag	What it does
stat	Count events for a command run
record -g	Sample with call-graph (stack) info
report	Analyze the recorded perf.data
-F <hz>	Sampling frequency
-e <event>	Select specific counters/events

Common errors in CI

"You may not have permission to collect stats. ... perf_event_paranoid setting is N" - lower it (sysctl kernel.perf_event_paranoid=1 or -1) or run privileged; most CI containers default to a restrictive value. In containers perf also needs CAP_PERFMON/CAP_SYS_ADMIN and a matching kernel-tools package; "WARNING: perf not found for kernel X" means the perf binary version mismatches the host kernel. Hardware counters are often unavailable on virtualized/cloud runners - fall back to perf stat with software events or use -e task-clock.