perf(1)
Analyze CPU performance, trace system events, and profile running processes.
Synopsis
perf [--version] [--help] [OPTIONS] COMMAND [ARGS]Description
perf is a powerful performance analysis tool for Linux that collects and analyzes CPU cycles, cache misses, branch predictions, memory access patterns, and other hardware events. It works with the kernel's performance monitoring infrastructure to profile applications and the entire system with minimal overhead.
Common workflows include recording performance data with perf record, examining results with perf report, and generating flame graphs or detailed call chains. It can monitor single processes, specific functions, or system-wide activity.
Common options
| Flag | What it does |
|---|---|
record | Record performance data into perf.data; use with -p PID or -c COMMAND |
report | Display recorded performance data in an interactive TUI or text format |
-p PID | Profile process with specific PID (with record/top/stat) |
-c COMMAND | Run and profile a command (e.g., perf record -c 'my_app arg1') |
-F FREQ | Sample at FREQ hertz (default 1000); higher = more precise, more overhead |
-e EVENT | Record specific event (e.g., cycles, cache-misses, page-faults); list with perf list |
-g | Record call graph (stack traces) for flame graphs and backtrace analysis |
top | Live profiling; shows hottest functions in real-time like htop for CPU |
stat | Show aggregate event counts (IPC, cache-miss ratio, etc.) without recording |
list | List available events; useful for finding what to monitor with -e |
Examples
Profile running process for 10 seconds, save to perf.data
perf record -p $(pgrep my_app) sleep 10Run command under profiling, then interactively view hottest functions
perf record -c 'my_app --arg' && perf reportLive real-time profiling of process 1234; press 'h' for help in TUI
perf top -p 1234Show summary stats (cycle count, cache misses, page faults) for one run
perf stat -e cycles,cache-misses,page-faults -c 'my_app'Capture call stacks and generate flame graph for visualization (requires stackcollapse and flamegraph scripts)
perf record -F 99 -g -c 'my_app' && perf script | stackcollapse-perf.pl | flamegraph.pl > flame.svgFind all available cache-related events you can monitor
perf list | grep cachePrint text report of top functions to stdout (useful for scripts)
perf report --stdio | head -30Use DWARF debug info for better call chains (needs -g flag and debug symbols)
perf record --call-graph dwarf -c 'my_app'