Inspect and Validate a trace-cmd Version 7 Trace File

trace-cmd.dat.v7 is the current on-disk format for a trace.dat file, and this guide checks one against it without editing a single byte. You will confirm whether trace-cmd accepts the file, then inspect the metadata that explains how its binary sections should be read.

This uses trace-cmd 3.2.0 from package version 3.2-1ubuntu2, and the version 7 format documented by the installed trace-cmd.dat.v7(5) manual page. Allow about fifteen minutes. You need a shell, the trace-cmd package, and a trace file you can read; no command below needs elevated privileges unless the file itself is restricted. The whole workflow is read-only: nothing here records a new trace, resets tracing, or rewrites the input.

1. Check the installed tools

Confirm the command and package before you interpret its output. Otherwise you risk diagnosing a file with a different trace-cmd build than the one whose manual page you have read:

$ command -v trace-cmd
/usr/bin/trace-cmd
$ dpkg-query -W -f='${Package} ${Version}\n' trace-cmd
trace-cmd 3.2-1ubuntu2
$ trace-cmd --version
trace-cmd version 3.2.0 (not-a-git-repo)

Checkpoint: if trace-cmd --version fails, install or repair the package through your normal system administration process. Do not substitute a guessed decoder for a missing command.

2. Validate the file without changing it

Use dump --validate with an explicit input path. Keeping -i in the command keeps the example safe even when the file is not called trace.dat:

$ TRACE_FILE='/path/to/trace.dat'
$ trace-cmd dump --validate -i "$TRACE_FILE"
File /path/to/trace.dat is a valid trace-cmd file

The path above is a placeholder: replace it with a real readable file. A non-zero exit status or an error message means trace-cmd did not accept the file; it does not prove the file is merely an ordinary compressed archive or text file, so do not skip straight to that conclusion. The command reads the file only. It does not repair a damaged header, decompress it in place, or delete anything.

3. Read the metadata summary

Once validation succeeds, ask for the default summary explicitly. It reports the initial format and a short description of every section trace-cmd found:

$ trace-cmd dump --summary -i "$TRACE_FILE"
Tracing meta data in file /path/to/trace.dat:
        [Initial format]
                7       [Version]
                0       [Little endian]
                8       [Bytes in a long]
                4096    [Page size, bytes]
        ...

Exact section sizes and counts depend on the recording host, but these facts are worth pulling out:

Do not infer that a version 7 file was collected by trace-cmd version 7. The format version and the application version are two separate pieces of metadata that happen to share a number sometimes.

4. Inspect the options and event inventory

The options section is mandatory in version 7, while other sections are optional. Ask trace-cmd to print the options when you need the recording context:

$ trace-cmd dump --options -i "$TRACE_FILE"
[Options]
...

Options can carry the trace clock, host identity, CPU count, application version, process maps, time offsets, guest relationships and offsets to other sections. It is metadata, not a replacement for the recorded events themselves. To see the event systems stored in the file, combine the summary with --systems:

$ trace-cmd dump --summary --systems -i "$TRACE_FILE"
...     [Events format, ... systems]
        sched ... [system, events]
        irq ...   [system, events]

Use the names and counts as a quick plausibility check only. A system listed in the event formats is not proof that every event in that system actually appears in the trace data.

5. Inspect the trace data locations

Version 7 stores the per-CPU flyrecord data in its own dedicated section, and the option metadata points to it with each CPU's data offset and size. Print those values with:

$ trace-cmd dump --flyrecord -i "$TRACE_FILE"
[Flyrecord tracing data]
        ... [offset, size of cpu 0]
        ... [offset, size of cpu 1]

Tip: a zero-sized CPU entry can be completely normal; that CPU may just have contributed no trace pages. Do not edit offsets with a hex editor: an incorrect offset can make a reader interpret unrelated bytes as event data.

6. Understand what the file contains

The first bytes give a compact format identity. A version 7 file begins with the three-byte magic value 17 08 44, followed by the seven ASCII bytes tracing and the null-terminated version string 7. The next bytes identify endianness and the target userspace long size, and after that every number uses the file's declared byte order.

Everything else is a set of sections, each with a header holding an ID, flags, a string ID and a size. Flag bit 1 means the section is compressed. The compression header names the algorithm and gives its version; none means the file data is not compressed. Large flyrecord and latency sections use their own chunked compression layout, aligned to the recorded trace page size.

That is why file, strings or less are poor primary inspection tools here: this is a structured binary container with offsets, lengths and optional compression, not a text file. Use trace-cmd to decode it, and reach for the manual page when you need to implement a compatible reader.

7. Produce readable event output

Once the metadata checks pass, use report for the human-readable trace rather than parsing the binary file yourself:

$ trace-cmd report -i "$TRACE_FILE" | less

This command only reads the input and writes a report to standard output. If you need full event timestamps, the installed report manual documents the -t option:

$ trace-cmd report -t -i "$TRACE_FILE" | less

For a damaged or unfamiliar file, go back to dump --validate and dump --summary before trying filters. A report failure can be caused by missing or incompatible event metadata even when the file itself has a recognisable header.

Done means