Run perf test Safely and Read Its Results

A single passing line from perf test tells you almost nothing about the tests you did not run, and a skipped test is easy to mistake for a pass. This guide gets you discovering the sanity tests on a Linux host, running a small named subset, and investigating a failure properly. Allow about 15 minutes for a first run.

You need a shell, the perf executable matching the running kernel where possible, and the linux-tools-common documentation package. Most discovery commands are unprivileged; some hardware and tracing checks may need elevated privileges.

1. Check the installed tool before running tests

The manual page installed here comes from linux-tools-common 6.8.0-142.142 and describes the perf test subcommand: there is no separate executable called perf-test. Check what your shell will actually run:

$ command -v perf
/usr/bin/perf
$ perf --version
WARNING: perf not found for kernel 6.8.0-139
... linux-tools-6.8.0-139-generic ...

The exact warning depends on the running kernel. On this host the common package supplies /usr/bin/perf, but the kernel-specific implementation is missing, so the command cannot be treated as a validated test runner. Install the matching tools through your normal distribution process, then repeat perf --version. Do not copy the warning's package names blindly to another distribution.

2. List the tests without running them

Start with the list: it is the safest way to learn the test numbers and the name fragments the installed build accepts.

$ perf test list
1: mmap basic
2: perf data file format
3: probe finder
...

Names, numbering and final output vary with the perf version, architecture and build options, so the useful result is a numbered inventory rather than a fixed list. A name fragment can narrow it:

$ perf test list mmap

Do not build automation around a fixed test number: numbers can move as tests are added or removed. Prefer a distinctive fragment when you need the same check across machines, and check the list first to confirm what it actually matches.

3. Run a narrow, repeatable check

Run one known fragment before asking for the complete suite. For example, if the list contains a test named with mmap:

$ perf test mmap
  1: mmap basic: Ok

That output is representative rather than a promise of exact numbering or wording. A successful command returns status 0, but a single passing test says nothing about tests you did not select. Capture the status explicitly when using the result in a script:

$ perf test mmap
status=$?
printf 'perf test status: %s\n' "$status"
test "$status" -eq 0

4. Run the full suite when the host is ready

Once the focused check works, run every available sanity test:

$ perf test

The suite can exercise linked-in routines and scripts found by perf. Some tests depend on hardware, kernel configuration, trace support or access to performance events. A failure is evidence that one check did not complete as expected, not that every perf feature is broken. Read the test name and its diagnostic, then rerun that test by fragment or number.

Use verbose output for the next diagnostic run:

$ perf test -v mmap

-v and --verbose are equivalent in this installed interface. Verbose output can expose helper commands and environment assumptions that the short result hides.

5. Skip a known blocker deliberately

If one test is known to be unsuitable for this host, skip it with its numeric identifier from the current list:

$ perf test -s 7

The manual defines -s and --skip as a comma-separated numeric list, so several tests can be skipped at once with a value such as -s 7,12. Record the skipped numbers beside the result: a suite that completes with a test skipped is not equivalent to a complete suite, and the number may refer to a different test after an upgrade.

For a diagnostic experiment, -F or --dont-fork runs every selected test in one process rather than forking a child for each:

$ perf test --dont-fork mmap

This changes the isolation model, so use it to investigate a reproducible problem, not as an unexamined default. If a test behaves differently, compare both runs and keep the original result.

6. Handle permissions and special tests

Some tests need access to performance monitoring or tracing facilities. First retry the smallest failing test as your normal user and read the diagnostic. If your operational policy permits it, compare with elevated privileges:

$ sudo perf test -v <test-number-or-fragment>

Replace the placeholder with an identifier from perf test list. Warning: sudo can change the environment, accessible files and security context, so a root pass does not prove an ordinary service account can use the same feature. Never grant broad privileges merely to silence one test failure.

--dso supplies a shared object for the Symbols test:

$ perf test --dso /path/to/libexample.so symbols

Use a real shared object the test is intended to inspect. This option does not install, modify or repair a library. Keep test files in a controlled directory and avoid pointing diagnostics at untrusted binaries.

Common traps

• Missing build for the running kernel: install or select the matching kernel-tools package, then check the version again.
• Failure after a kernel or firmware change: save the full verbose output and compare the same fragment on the old and new systems.
• A test leaves files or a helper process behind: stop and inspect before deleting anything; the short manpage does not promise a universal cleanup location.
• A permanent skip list is not a fix: record the reason, owner and expiry for any temporary skip, then rerun the unskipped test once the kernel, permissions or hardware issue is addressed.