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.

• You need: a readable input file, free space for the output, and the trace-cmd command.
• It will not touch: kernel tracing state or the original input file. This is a read-and-rewrite job, not a new recording.

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.

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")"

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.

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

Common traps

• Omitting -i. trace-cmd then looks for trace.dat in the current directory; it will not go hunting for an arbitrary trace file.
• Forgetting the output. It is mandatory, either via -o or as the final command-line item. A compression setting is not a destination name.
• Confusing any with none. any picks an available compressor; none deliberately writes an uncompressed trace.
• Trusting the rewrite alone. A successful conversion is not proof another program can read the file. Verify with the target consumer as well as with trace-cmd report.