Convert perf.data Safely with perf data convert

You will turn an existing perf data file into either a CTF data directory or a JSON file, while leaving the source recording untouched. Allow about 15 minutes for a small file and longer for a large recording or a slow storage device. The commands below are ordinary user commands unless the input or destination is deliberately protected by permissions.

1. Check the installed tool and source file

This guide follows the installed perf-data(1) manual from Debian's linux-tools-common package, version 6.8.0-142.142. The manual describes the perf data convert subcommand and its convert operation. The exact perf binary can be kernel-specific, so check both the package and the executable before starting.

$ command -v perf
/usr/bin/perf
$ dpkg-query -W -f='${Package} ${Version}\n' linux-tools-common
linux-tools-common 6.8.0-142.142
$ test -r /path/to/perf.data && echo 'input is readable'
input is readable

On this machine, invoking perf may print a warning if the matching kernel-specific tools package is absent. Treat that as a setup failure, not as a conversion result. Install the matching package through your normal system process, then repeat the command and confirm that perf --version returns a version instead of only the warning.

2. Choose a new destination

Conversion reads the input named with -i. Pick a destination that does not already contain valuable data. JSON conversion takes an output filename; CTF conversion takes a directory. Keep the input file until you have inspected the result.

$ mkdir -p "$HOME/perf-converted"
$ test ! -e "$HOME/perf-converted/perf.json" && echo 'JSON destination is unused'
JSON destination is unused

The mkdir command changes state only in your own home directory. If you need to abandon the empty directory later, remove that specific directory after checking it contains nothing useful. Do not use a broad recursive removal command against a recording directory.

3. Convert samples to JSON

Use --to-json followed by the JSON filename, and select the input with -i. This is the most convenient form when another script or inspection tool expects one JSON file.

$ perf data convert \
    -i /path/to/perf.data \
    --to-json "$HOME/perf-converted/perf.json"
$ test -s "$HOME/perf-converted/perf.json" && echo 'JSON output is non-empty'
JSON output is non-empty

The converter writes sample events by default. A successful exit status and a non-empty file are useful checks, but they do not prove that every event in the recording was included. The manual says that non-sample events such as communication and fork events are excluded by default.

Inspect the beginning without editing the file:

$ sed -n '1,24p' "$HOME/perf-converted/perf.json"

JSON layout and the amount of output depend on the recording and the installed converter. If the command fails, check the error, remove only an incomplete destination if necessary, and retry after correcting the input path or permissions. The original perf.data remains the recovery point.

4. Include every event when required

For a trace where process activity matters, add --all. The option changes the conversion scope: it includes non-sample events as well as samples. Do not add it automatically to every export, because it can produce more output than a consumer needs.

$ perf data convert \
    -i /path/to/perf.data \
    --to-json "$HOME/perf-converted/perf-all.json" \
    --all
$ test -s "$HOME/perf-converted/perf-all.json" && echo 'full JSON output is non-empty'
full JSON output is non-empty

Keep the two JSON files separate while comparing them. A smaller default export is not necessarily broken; it may simply contain samples only. Record whether --all was used alongside the output so a later analysis does not confuse the two datasets.

5. Convert to CTF instead

Use --to-ctf when the next tool consumes the Common Trace Format. Supply a directory path rather than a filename. Create a fresh directory first so its contents are clearly attributable to this conversion.

$ ctf_dir="$HOME/perf-converted/perf-ctf"
$ test ! -e "$ctf_dir" && mkdir "$ctf_dir"
$ perf data convert \
    -i /path/to/perf.data \
    --to-ctf "$ctf_dir"
$ find "$ctf_dir" -maxdepth 2 -type f -print

The exact CTF directory layout is produced by the installed converter. An empty directory after a successful-looking shell sequence is a reason to inspect the command's exit status and diagnostics, not to assume that conversion worked.

6. Handle timestamps deliberately

Add --tod when the converted timestamps need to be expressed as wall-clock time. This is a semantic change to the exported data, not a display preference. Use it when the receiving analysis expects time of day and you have checked that the recording's clock context makes that interpretation meaningful.

$ perf data convert \
    -i /path/to/perf.data \
    --to-json "$HOME/perf-converted/perf-wall-clock.json" \
    --tod
$ test -s "$HOME/perf-converted/perf-wall-clock.json" && echo 'wall-clock export is non-empty'
wall-clock export is non-empty

Keep a separate output for this variant. Do not overwrite an earlier export merely to change timestamp interpretation; preserving both makes comparison and recovery straightforward.

7. Diagnose without hiding errors

Use --verbose for more detail, including counter-open errors. Add -f only when you understand what complaint you are suppressing. It means force, so it can turn a warning that deserves investigation into a conversion that appears to have completed.

$ perf data convert --verbose \
    -i /path/to/perf.data \
    --to-json "$HOME/perf-converted/perf-verbose.json"
$ printf 'exit status: %s\n' "$?"
exit status: 0

If the status is non-zero, do not publish or analyse the destination as complete. Check that the source is a perf data file, that the destination's parent is writable, and that the installed perf matches the running kernel closely enough to process the recording. Elevated privileges do not repair a missing or incompatible tool, and sudo is normally unnecessary.