Keep perf Build IDs Useful with buildid-cache

perf buildid-cache manages the cache that lets perf resolve symbols in a recording even after the original binary has moved or changed. This guide covers inspecting it, adding and updating entries, and removing them without losing the ability to annotate an old recording.

Allow about 15 minutes. You need the matching perf tools package and a shell; the examples use ordinary user access unless a command says otherwise. This follows the installed perf-buildid-cache(1) manual. On this machine the relevant package is linux-tools-common version 6.8.0-142.142, present here, but the kernel-specific perf executable is not, so the final command checks must 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 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 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.

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 adds detail, including 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 the current pathname. That matters when a binary is replaced in place: the new file can carry a different build ID while an older entry stays 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.

4. Check for missing build IDs before analysis

When a perf recording cannot resolve all 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 fixed just by adding whichever file shares the name: verify it 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, deliberately: they may still be required to annotate old or remote data. The replacement happens 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 rather than 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

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

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