Read the Events Stored in a perf.data Capture

You will finish with a quick way to see which events a perf.data capture contains, then narrow the display to sampling frequencies, event groups or tracepoint fields. The guide follows the installed perf-evlist(1) manual from the Debian linux-tools-common package, version 6.8.0-142.142.

Allow about ten minutes. You need a shell, a readable perf data file and a working perf installation. The inspection commands only read the capture. They do not start profiling, change kernel settings or alter the input file. Reading a file owned by another user may require permission from its owner or an administrator; do not make the capture world-readable just to get past that error.

1. Check the local installation

First confirm which command your shell will run and which package supplies the shared perf tools:

$ 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 exact path may differ. On this machine, the package is installed but the wrapper reports that the kernel-specific perf binary for kernel 6.8.0-139 is missing. Install or select the matching kernel tools through your normal system administration process before treating that warning as an event-list failure. This guide does not install packages or alter the host.

Checkpoint: run perf --version. It should print a version rather than a missing-tools warning. If it cannot run, stop here and fix the installation first.

2. List the events in a capture

Change /path/to/perf.data to the file you intend to inspect, then run:

$ perf evlist -i /path/to/perf.data
EVENT_NAME_1
EVENT_NAME_2

The output is the event names recorded in that file. The names above are deliberately placeholders: a real capture might contain hardware events, software events, tracepoints or a mixture of them. Do not infer the events from the command used to create the capture; inspect the file you are actually about to analyse.

-i and --input= select the input file. If you omit them, perf evlist uses perf.data in the current directory, unless standard input is a FIFO. Using an explicit path is less distracting when several captures are present:

$ test -r /path/to/perf.data && perf evlist --input=/path/to/perf.data
EVENT_NAME_1
EVENT_NAME_2

The test command prevents a confusing second error when the path is wrong or unreadable. Its success only proves that the file is readable; perf evlist still has to recognise a valid perf data file.

3. Show the sampling frequency

To display the sample frequency used for each event, add --freq or its short form -F:

$ perf evlist --input=/path/to/perf.data --freq
EVENT_NAME_1  FREQUENCY_OUTPUT
EVENT_NAME_2  FREQUENCY_OUTPUT

The labels in this block stand for output produced by your capture. The value is not a setting you can safely assume from the command line that recorded it: event-specific configuration and the capture's metadata are what matter. Use this view when comparing two recordings that appear to profile the same event but have different data volumes.

Checkpoint: save the command and its output together if you are comparing captures. A bare event list tells you what was requested or recorded; the frequency view adds the sampling detail that can explain a larger file or a noisier profile.

4. Inspect groups and all fields

Some recordings place events into groups. Ask for group information with --group:

$ perf evlist -i /path/to/perf.data --group
EVENT_AND_GROUP_INFORMATION

This is an inspection option, not a way to regroup events after the capture. If you need to change grouping, record a new capture with an appropriate profiling command; do not edit the original file.

For the most detailed event-list display, use --verbose:

$ perf evlist -i /path/to/perf.data --verbose
ALL_AVAILABLE_EVENT_FIELDS

The manual describes this as showing all fields. The exact columns and values are version and capture dependent, so scripts should not scrape this human-oriented display unless you have tested against the perf version that will run them.

5. Inspect tracepoint field names

If the capture includes tracepoints, add --trace-fields to request their field names:

$ perf evlist --input=/path/to/perf.data --trace-fields
TRACEPOINT_EVENT_AND_FIELD_INFORMATION

This can help you decide which recorded fields are available before you write a filter or investigate a report. It does not add fields that were absent from the capture, and it does not alter the tracepoint definition in the running kernel.

For a broad inventory, combine the options that answer your question rather than jumping straight to verbose output:

$ perf evlist -i /path/to/perf.data --group --freq --trace-fields

Run the simpler event-list command first. It gives you a checkpoint and makes it easier to tell whether a later display option caused an error or merely produced more detail.

6. Handle errors without damaging the capture

A missing file, a permission failure or an invalid capture should be investigated at the input boundary. Check the path and permissions without changing them:

$ stat /path/to/perf.data
$ test -r /path/to/perf.data
$ printf 'readability status: %s\n' "$?"
readability status: 0

That status is from test, not from perf evlist. To capture perf's own result, run it as the last command in a small check:

if perf evlist --input=/path/to/perf.data; then
    printf '%s\n' 'event list read successfully'
else
    status=$?
    printf 'perf evlist failed with status %s\n' "$status" >&2
    exit "$status"
fi

Do not treat every failure as a reason to use --force. The installed manual describes --force as telling perf not to complain and to proceed, but it does not turn an unreadable or corrupt file into a trustworthy capture. Try it only when you understand the warning and have a copy of the original file. No example here changes state, so there is no undo operation; preserve the original capture and work on a separate copy if another tool will modify data.