linux-perf
Linux’s perf tool uses the kernel’s performance-counter framework—including hardware PMU features, software counters, and tracepoints—to sample CPU activity and expose functions where samples accumulate as hotspots.
This is a general guide based on the man7.org manuals for perf(1), perf-record(1), perf-report(1), and perf-top(1), checked on 2026-09-02. Exact behavior can vary with the kernel, CPU, and permission settings.
What is perf?
Short answer: It works with Linux’s kernel-based performance-counter framework, covering hardware PMU capabilities as well as software counters and tracepoints.
PMU means Performance Monitoring Unit, the CPU’s performance-monitoring facility. This article focuses on one practical path: use CPU samples associated with functions and symbols to identify hotspots.
Use record to save a profile for later analysis and report to read it. Use top for live observation; stat gathers event counts, while list shows symbolic event types that can be used with -e.
gdb is an interactive debugger, and strace traces system calls; this tool uses performance-counter samples to show hotspots.
How do you record a profile?
Short answer: record runs a command, collects a performance-counter profile, and writes it to perf.data by default without displaying the result immediately.
The documented minimal forms cover system-wide collection, a command to run, or an explicitly selected event.
perf record -a
perf record -- <command>
perf record -e cycles -- <command>Choose an event with -e; symbolic names can be checked with perf list, and a raw event can be written as rN. Use -o for an output file, -p or -t for an existing process or thread, and -C for a CPU list.
Sampling frequency, event period, and call-graph collection correspond to -F, -c, and -g. An event filter can follow the event as --filter; -a selects system-wide collection, and the default output file is perf.data.
How do you read the report?
Short answer: report reads the perf.data written by record and displays the recorded performance-counter profile, bringing sample-heavy functions and symbols into view.
When standard input is not a FIFO, the default input is perf.data. Use perf report for the default path or perf report -i perf.data when you want to name the input explicitly.
perf report
perf report -i perf.dataThe default sort keys are overhead,comm,dso,symbol, with overhead first. This ordering puts functions and symbols with greater sample overhead earlier, which makes hotspot candidates easier to inspect.
Use -n to show sample counts, -s to choose sort keys, and -U to hide unresolved entries. Child-call accumulation can be controlled with --children or --no-children.
How do you view it live?
Short answer: top generates and displays a performance-counter profile in real time, so it does not require a previously saved profile.
The minimal command is perf top. System-wide collection is selected by -a and is the default; -C, -e, -F, and -c cover CPU lists, events, frequency, and event period, while -p and -t target an existing process or thread.
perf topEnable call-graph recording with -g. Child-call accumulation is enabled by default and can be disabled with --no-children; -K and -U hide kernel and user symbols, while -d controls refresh delay and -E controls how many functions are displayed.
Annotation functionality requires a vmlinux path supplied with -k. The saved path is record to perf.data and then report; the live path is top, and neither is universally better.
FAQ
Short answer: Separate recording, reporting, and live display by purpose, then account for event selection and differences in permissions and environment.
Do record and report have to be used together? For the saved-profile workflow, record creates perf.data and report reads it. A live check can use top without going through that saved-file path.
Do I need record before top? No. top generates and displays the performance-counter profile in real time.
Is cycles the only event I can use? No. Select a PMU event with -e; use perf list to inspect the symbolic event types available for that option.
Why can permissions or results differ between environments? Kernel, CPU, and permission settings can change the detailed behavior. If collection or output differs, first check the event and target scope permitted in that environment.
Sources
Short answer: The core facts and command forms here come only from the four official man7.org manuals checked on 2026-09-02.
They are listed in the same order as the article’s path: overview, recording, reporting, and live profiling.