perf stat: CPU Counters for a Command
perf stat runs a command and prints aggregate performance counters such as cycles, instructions, and cache misses.
perf stat is the first stop for understanding why a workload is slow: is it CPU-bound, cache-bound, or branch-bound? It aggregates counters over the whole run.
What it does
perf stat launches a command and collects hardware counters (cycles, instructions, cache references and misses, branch misses) and software counters (context switches, page faults), printing totals and derived rates like instructions per cycle.
Common usage
perf stat ./my-program
# specific events, repeated 5 times for stddev
perf stat -e cycles,instructions,cache-misses -r 5 ./my-program
# attach to an already running process
perf stat -p 12345 -- sleep 10Options
| Flag | What it does |
|---|---|
| -e <events> | Comma-separated event list (cycles, instructions, cache-misses, ...) |
| -r N | Repeat the run N times and report mean and stddev |
| -p <pid> | Attach to an existing process |
| -a | System-wide counting across all CPUs |
| -d | Detailed mode: add more cache-level counters |
Common errors in CI
"Access to performance monitoring and observability operations is limited" or "You may not have permission to collect stats ... perf_event_paranoid" means the kernel setting blocks it; lower it with sysctl kernel.perf_event_paranoid=1 (or -1) on the host, which is often impossible on managed runners. "<not supported>" or "<not counted>" for an event means the CPU or a virtualized runner does not expose that hardware counter; VMs frequently lack them. Fall back to software events (task-clock, context-switches) that work without hardware PMU access.