Run perf test Safely and Read Its Results

You will use perf test to discover the sanity tests available on a Linux host, run a small named subset, and investigate a failure without mistaking a skipped test for a pass. 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. The executable is not a separate command called perf-test. Check what your shell will 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.

Checkpoint: continue only when perf --version identifies a usable build, or when you are deliberately diagnosing why the matching build is absent.

2. List the tests without running them

Start with the list. This is the safest way to learn the test numbers and the name fragments accepted by the installed build:

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

The names, numbering and final output vary with the perf version, architecture and build options. The useful result is a numbered inventory. A name fragment can also narrow the listing:

$ 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 inspect the list first to confirm what it 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

Keep the test output and the perf --version result together. They make a later comparison meaningful when the kernel, CPU, permissions or perf build changes.

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; it is not automatically evidence 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

The -v and --verbose forms 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 selected tests can be skipped 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 all selected tests in one process rather than forking a child for each test:

$ 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. sudo can change the environment, accessible files and security context, so a root pass does not prove that an ordinary service account can use the same feature. Never grant broad privileges merely to silence one test failure.

The --dso option supplies a DSO for the Symbols test:

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

Use a real shared object that 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.

7. Recover from an incomplete or misleading run

If perf says it cannot find the build for the running kernel, install or select the matching kernel-tools package, then check the version again. If a test fails after a kernel or firmware change, save the full verbose output and compare the same fragment on the old and new systems. If the test leaves files or a helper process behind, stop and inspect before deleting anything; the short manpage does not promise a universal cleanup location.

Do not fix a failure by adding it to the skip list permanently. Record the reason, owner and expiry for any temporary skip, then rerun the unskipped test after the kernel, permissions or hardware issue is addressed.