Keep perf Build IDs Useful with buildid-cache

You will finish with a controlled way to inspect and maintain the perf build-ID cache, including a check for missing IDs and a safe path for replacing an existing entry. Allow about 15 minutes. You need the matching perf tools package and a shell. The examples use ordinary user access unless a command explicitly says otherwise.

This guide follows the installed perf-buildid-cache(1) manual. On this machine the relevant package is linux-tools-common version 6.8.0-142.142. That package is present here, but the kernel-specific perf executable is not available, so the final command checks must be run on a host with the matching tools installed.

1. Check that the matching perf command is available

Start with a read-only check. Do not assume that installing linux-tools-common alone provides a runnable command for every kernel:

$ command -v perf
$ perf --version

On Ubuntu, a warning such as perf not found for kernel ... means that the kernel-specific tools package is missing or does not match the running kernel. Install the package through your normal system administration process, then rerun the two checks. Do not use sudo for cache maintenance just because the command is a performance tool. A root invocation can write root's cache instead of your user's cache.

2. Inspect the current cache

List valid cached binaries before changing anything:

$ perf buildid-cache --list
$ perf buildid-cache --list --verbose

--list reports valid binaries in the cache. --verbose gives more detail and is also useful when you need to see where a file is created. An empty listing is a valid state, not proof that perf is broken.

The cache is keyed by build ID rather than only by the current pathname. That matters when a binary is replaced in place: the new file can have a different build ID while an older entry remains useful for annotating an old or remote perf.data file.

3. Add a binary without replacing the original

Use --add with a readable executable or shared object:

$ perf buildid-cache --add=/path/to/application
$ perf buildid-cache --list --verbose

The command scans the target binary for statically defined tracing (SDT) information as part of managing the cache. It copies cache data; it does not rewrite the input path. Use an absolute path in scripts so a later working-directory change cannot select a different file.

If adding the same file produces a complaint, inspect the message before reaching for --force. The manual describes --force as suppressing the complaint and proceeding. It is not a general repair option, and it does not make an unreadable or invalid file useful.

4. Check for missing build IDs before analysis

When a perf recording cannot resolve all of its binaries, ask the cache which IDs are missing for a specified file:

$ perf buildid-cache --missing=/path/to/application

This is a diagnostic query. Save its output with the recording's investigation notes, then add the corresponding binary if you have a trusted copy. A missing ID is not automatically fixed by adding whichever file happens to have the same name: verify that the file comes from the same build as the recorded workload.

5. Update one matching entry and keep older history

Use --update when the cache already contains the same build ID and you need to replace that cached file:

$ perf buildid-cache --update=/path/to/application
$ perf buildid-cache --list --verbose

Update does not remove older entries. That is deliberate: older entries may still be required to annotate old or remote data. The replacement occurs only when an existing cache entry has exactly the same build ID. If your rebuilt binary has a new build ID, add it as a new entry instead of expecting --update to erase history.

6. Remove entries only when you understand the impact

--remove removes the cached binary with the same build ID as the specified file:

$ perf buildid-cache --remove=/path/to/application
$ perf buildid-cache --list --verbose

This changes the cache and can make later annotation of a recording less complete. Keep the original binary and recording so you can add the entry again if needed. The undo is the corresponding add command:

$ perf buildid-cache --add=/path/to/application

There are two broader purge operations. --purge=/path/to/application removes cached binaries, including older caches, associated with the specified path. --purge-all flushes the entire cache. Treat both as destructive actions. Review the verbose listing and copy any evidence you need before running either command. Neither operation has a selective undo beyond re-adding binaries that you still possess.

7. Handle the kcore case separately

--kcore adds the current host's /proc/kcore to the cache. Reading it requires root permissions, and the command also copies kallsyms and modules from the same directory. The cached files are created readable only by root:

$ sudo perf buildid-cache --kcore --verbose

Use elevated privileges here only when your host policy permits this kernel-symbol capture. The manual warns that running perf as root may update root's cache, not the invoking user's cache. Check the verbose output and then inspect the cache as the user who will run perf analysis. A kcore copy is not the whole core image: it contains code sections, alongside the related symbol and module files.

If a kcore with the same build ID already has the same modules at the same addresses, another copy is not added. Do not interpret the absence of a new file as a failure without checking verbose output.