Convert trace-cmd Files to a New Version or Compression

trace-cmd convert rewrites an existing trace.dat file into a new one with a chosen file version and compression, and it never touches the source. Budget about ten minutes, plus however long it takes to copy a large trace, and have spare disk space for the second copy.

The examples run as an ordinary user. Only reach for sudo if the input or destination directory is deliberately locked down, and fix the directory permissions rather than running the whole conversion as root.

1. Check the installed command

Confirm which executable runs and read the local help before you commit to anything:

$ command -v trace-cmd
/usr/bin/trace-cmd
$ trace-cmd --version
trace-cmd version 3.2.0 (not-a-git-repo)
$ trace-cmd convert --help

The help text names trace.dat as the default input, makes the output mandatory, and lists the file versions and compression options it supports. If your installed version reports something different, follow that help text over this guide.

Checkpoint: you have a working trace-cmd executable and know the version whose behaviour you are relying on. This example uses trace-cmd 3.2.0 from Ubuntu package 3.2-1ubuntu2.

2. List the compression algorithms on offer

Ask trace-cmd which named compression algorithms it supports on this machine:

$ trace-cmd list -c
Supported compression algorithms:
        zstd, 1.5.5

The output is installation-specific: here, only zstd is available. any tells trace-cmd to pick the best algorithm it has; none switches compression off entirely. A named algorithm is only valid once this check has shown it is supported.

3. Pick input and output paths

Set both paths as shell variables so the commands below stay readable, replacing the placeholders with real paths on your machine, then check the input is readable and the output does not already exist:

$ input=/path/to/existing-trace.dat
$ output=/path/to/existing-trace-v7-zstd.dat
$ test -r "$input" && test ! -e "$output" && printf 'ready\n'
ready

A missing ready means stop and look at the paths before continuing:

$ ls -l -- "$input"
$ ls -ld -- "$(dirname -- "$output")"

Safety boundary: never point the output at the input. Do not assume an existing file at the destination is harmless either: pick another name, or make a deliberate backup before you overwrite it. Keeping the original input is your simplest way back.

4. Convert to version 7 with automatic compression

Version 7 with automatic compression is the default output when the installed build supports compression. Spell out both choices anyway in any script, so a future default change cannot silently alter an archive:

$ trace-cmd convert \
    -i "$input" \
    -o "$output" \
    --file-version 7 \
    --compression any
$ status=$?
$ printf 'trace-cmd exit status: %s\n' "$status"
trace-cmd exit status: 0

The exit status is the useful success signal here; trace-cmd does not print a running commentary while it works. A status of 0 means the conversion finished, not that the destination is definitely the file you meant to write, so keep going with the checks below.

Checkpoint: the new path exists, the original path is still there, and the command returned status 0.

5. Use version 6 for an older reader

If whatever will read the file needs version 6, ask for it by name. The manpage documents only versions 6 and 7:

$ older_output=/path/to/existing-trace-v6-none.dat
$ trace-cmd convert \
    -i "$input" \
    -o "$older_output" \
    --file-version 6 \
    --compression none

This produces an uncompressed version 6 file. An older file version is not a guarantee of compatibility with every old reader: test the result with the actual reader, and keep the source until that test passes.

6. Verify the file and the conversion

Check the file itself first. Confirm the destination is a regular file of a plausible size and that the input is still intact:

$ ls -lh -- "$input" "$output"
$ test -s "$output" && printf 'output is non-empty\n'
output is non-empty

Then let trace-cmd read it back. report is a separate trace-cmd command, and its output depends on the events in your trace, so save it or inspect its first lines rather than expecting one fixed transcript:

$ trace-cmd report "$output" > /tmp/trace-report.txt
$ status=$?
$ printf 'report exit status: %s\n' "$status"
report exit status: 0

If the report command fails, keep both the original and the failed destination for diagnosis. Check that you selected a supported compression algorithm, that the destination was fully written, and that the reader genuinely supports the requested file version. Do not delete the source to free space until the converted copy has passed a real compatibility check.

7. Recover from an unwanted output

A failed conversion should leave the input alone, but it can leave a half-written destination behind. Confirm the exact path before removing anything:

$ ls -l -- "$output"
$ rm -- "$output"
$ test ! -e "$output" && printf 'incomplete output removed\n'
incomplete output removed

Warning: rm is irreversible. Run it only against the destination you have just checked, never the original trace. If the output might be valuable or the path is uncertain, leave it in place and rename it for investigation instead.

Common traps

Done means