Find the Right perf Manual Page with perf help

perf help is how you find out which performance tools are actually installed before you waste time chasing the wrong subcommand. Allow about ten minutes. You will list the installed commands, open the manual for one of them, and learn to tell a perf command problem apart from a missing kernel-specific perf binary. The examples use Ubuntu's linux-tools-common package at version 6.8.0-142.142, with the wrapper and manpages installed on this machine.

1. Check the wrapper and package

Start with read-only checks. They do not need elevated privileges:

$ command -v perf
/usr/bin/perf
$ dpkg-query -W -f='${Package} ${Version}\n' linux-tools-common
linux-tools-common 6.8.0-142.142

• The dispatcher pattern: on Debian and Ubuntu, /usr/bin/perf can be a dispatcher. It looks for a binary matching the running kernel and then runs it.
• Two packages, two jobs: the common package supplies the dispatcher and shared documentation, while a kernel-specific tools package supplies the executable that does the work.

2. Show the normal command list

With no option and no command name, perf help prints perf's synopsis and a list of the most commonly used commands:

$ perf help
WARNING: perf not found for kernel 6.8.0-142

  You may need to install the following packages for this specific kernel:
    linux-tools-6.8.0-142-generic
    linux-cloud-tools-6.8.0-142-generic

  You may also want to install one of the following packages to keep up to date:
    linux-tools-generic
    linux-cloud-tools-generic

The exact warning depends on the running kernel and distribution packaging. On a host with the matching binary installed, the command list appears instead. Either way, this invocation only asks perf for its overview; it does not measure a process, record a trace or change system state.

3. List every available perf command

Use -a or --all when the common list is not enough:

$ perf help --all
...

• It wins any conflict. The option prints all available commands to standard output and supersedes any other option: combine --all with a command name and the all-commands listing wins, not the named command's manual page.
• Pipe it if you need to search. Keep the output in the terminal and use ordinary shell tools only when they are installed:

$ perf help --all | less

less is a separate pager; press q to leave it. If perf itself is missing, this pipeline still reports the perf error. The pager does not fix the missing executable.

4. Open a subcommand manual

Pass a perf command name after help to request its manual page. For example, stat measures counts while a command runs:

$ perf help stat

The documented behaviour is to use the man program by default. Your terminal switches to the manual viewer, so press q when you have finished reading. This does not run perf stat; it only asks for the documentation for that subcommand. Use the same pattern for another command from your list:

$ perf help record
$ perf help report

The command name must be one that the installed perf knows about. If the manual page is unavailable, check the relevant Linux tools package and the local manpage search path rather than guessing at a replacement command.

5. Use the help spelling that fits your habit

The top-level spelling perf --help is internally converted to perf help, so these requests are equivalent:

$ perf help
$ perf --help

Both forms show the overview when no command follows. For a subcommand manual, use the explicit form perf help COMMAND: it makes clear that COMMAND is a perf subcommand, not an option to the top-level program.

6. Diagnose the missing-binary case

On this machine, the wrapper reports that perf is not installed for kernel 6.8.0-142 and exits with status 2. Verify that result without using sudo:

$ uname -r
6.8.0-142-generic
$ perf help >/tmp/perf-help-output 2>/tmp/perf-help-error
$ printf 'exit status: %s\n' "$?"
exit status: 2
$ sed -n '1,12p' /tmp/perf-help-error
WARNING: perf not found for kernel 6.8.0-142

If your host gives the same warning, install the matching tools package through your normal administrator-approved process, then repeat step 1 and step 2. Do not copy the package name from this example to a different kernel flavour: the wrapper's own warning is the relevant hint for the machine you are repairing.