Find the Right perf Manual Page with perf help

You will use perf help to discover the installed performance-analysis commands, list the complete command set when needed, and open the manual for one subcommand. You will also be able to tell the difference between a perf command problem and a missing kernel-specific perf binary. Allow about ten minutes. 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

On Debian and Ubuntu systems, /usr/bin/perf can be a dispatcher. It looks for a binary matching the running kernel and then runs it. The common package supplies the dispatcher and shared documentation, while a kernel-specific tools package may supply the executable that does the work.

Checkpoint: if command -v perf prints nothing, the command is not on your PATH. If it prints /usr/bin/perf, continue. A visible command is not, by itself, proof that the matching binary is installed.

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. The important point is that this invocation asks perf for its overview; it does not measure a process, record a trace or change system state.

Do not treat a package hint as a universal installation command. Confirm the running kernel with uname -r, then use your normal package-management process and check the package name offered by your distribution. Installing packages changes the system and may require administrator access; it is outside this read-only discovery step.

3. List every available perf command

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

$ perf help --all
...

The option prints all available commands to standard output. It supersedes any other option. In practical terms, if you combine --all with a command name, do not expect the named command's manual page to open: the all-commands listing wins.

For a searchable list, keep the output in the terminal and use ordinary shell tools only when they are installed. For example:

$ 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 will switch to the manual viewer, so press q when you have finished reading. This command 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. That makes it 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

The temporary files contain help diagnostics only and can be removed after inspection with rm -- /tmp/perf-help-output /tmp/perf-help-error. That deletion is safe for these files but still irreversible, so check the names before running it.

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.