Find the Right Performance Events with perf list

You will use perf list to discover event names that can be passed to commands such as perf stat and perf record. You will narrow a large event catalogue, save a machine-readable listing, and recognise when an event exists in the catalogue but cannot be used by your account. Allow about 15 minutes for the first pass. The examples describe the perf interface shipped with Ubuntu's linux-tools-common version 6.8.0-142.142 on the system used for this guide.

This is an inspection workflow. It does not start a recording, change kernel settings or alter a service. The installed wrapper may require a matching kernel-specific linux-tools package before it can run; check that first rather than guessing which event names your CPU supports.

1. Check the installed command

Confirm that the command resolves and ask it for its version:

$ command -v perf
$ perf --version

On this host, the perf wrapper warns that it cannot find a tool for kernel 6.8.0-139, even though linux-tools-common is installed. That is a packaging or kernel-tools mismatch, not evidence that the event list is empty. Install the matching tools through your normal package-management process, then repeat this checkpoint. Do not use sudo merely to list events.

2. List the catalogue without descriptions

Start with a compact listing:

$ perf list --no-desc

With no category argument, perf list lists all known symbolic event types. The default includes descriptions, so --no-desc is useful when you are searching or redirecting the result. The names shown are candidates for the -e option accepted by other perf commands. A name appearing here does not guarantee that your user account can open it or that the current processor implements it.

To read a smaller result interactively, use the pager or a search command:

$ perf list --no-desc | less
$ perf list --no-desc | grep -i 'cache'

The second command searches rendered text, which is convenient for a quick look but fragile for automation. Keep the original listing when you need to review the context around a match.

3. Choose the right event family

The optional argument limits the listing. Use one or more of these categories:

• hw or hardware for hardware events.
• sw or software for software events.
• cache or hwcache for hardware cache events.
• tracepoint for tracepoints.
• pmu for kernel-supplied PMU events.
• sdt for statically defined tracepoints.
• metric for metrics, or metricgroup for metric groups with their metrics.

For example:

$ perf list --no-desc hw cache
$ perf list --no-desc tracepoint

When the argument is not one of those category names, perf treats it as an event glob. A tracepoint can also be filtered with a subsystem and event pattern, such as sched:*. Quote patterns that contain * so your shell does not expand them against files in the current directory:

$ perf list --no-desc 'sched:*'
$ perf list --no-desc '*cache*'

If the supplied text does not match as a category or glob, the command falls back to a substring search in event names. This makes interactive discovery forgiving, but it can return more results than an exact event name.

4. Inspect descriptions and resolution details

Once you have a likely event, ask for more context:

$ perf list --long-desc 'cache'
$ perf list --details 'cycles'

Descriptions are printed by default. --long-desc requests longer descriptions, while --details shows how named events are resolved internally and any extra expressions computed by perf stat. Use --deprecated when investigating an older script that refers to an event no longer shown by default:

$ perf list --deprecated 'cycles'

Do not silently substitute a similarly named event for a deprecated or missing one. Record the exact name and the machine on which you found it. Event meanings and availability are processor-specific, especially for PMU and raw events.

5. Save a listing for review or automation

For a report that another tool will parse, request JSON and write it to a new file:

$ perf list --json --output=perf-events.json hw

The default destination is standard output. --output= selects a file, and --json selects JSON output. Check the result before using it:

$ test -s perf-events.json && echo 'event listing written'
$ head -c 200 perf-events.json

Redirection and --output= can overwrite an existing file. If the old listing matters, choose a new filename or copy it first. This is the only state-changing example in this guide, and it changes only the named output file. Remove an unwanted temporary listing with your normal file-management process after checking that it is not needed.

6. Treat permissions and placeholders as separate problems

Listing an event and using it are different checks. The manpage states that ordinary users generally have access only to context-switched events, the CPU PMU's predefined events and some software events. Other PMUs and global measurements are normally restricted to root. Tracepoints also require read access to /sys/kernel/tracing. If a later measurement fails, first identify the event family and the access restriction instead of assuming the spelling is wrong.

An administrator can change the kernel's kernel.perf_event_paranoid policy, but that is a security-sensitive host-wide change and is outside this discovery guide. Do not lower it as a blind fix. If elevated access is approved for a specific measurement, run only that measurement with sudo, and document why it needs it.

Some PMU entries contain ?, for example hv_gpci/dtbp_ptitc,phys_processor_idx=?/. The question mark means a value must be supplied before the event can be used. It is not a literal event name. Use the displayed PMU syntax and the hardware documentation to fill the parameter.