Inspect a trace-cmd trace.dat File Without Replaying It

You will use trace-cmd dump to check a trace file, read its metadata summary, and narrow the output to the part you need. The command reads a file created by trace-cmd record; it does not start tracing, reset the kernel, or alter the input file.

Allow about ten minutes for a first inspection. You need a shell, the trace-cmd package, and a trace file that you are allowed to read. The examples use trace-cmd 3.2.0 from package version 3.2-1ubuntu2 on this machine. Output sizes, event names and CPU counts will differ between trace files.

1. Check the installed command

Confirm which executable is first in your path and record the package version. These are ordinary read-only commands and do not need elevated privileges:

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

The manpage calls the operation trace-cmd dump, not a separate trace-cmd-dump executable. If trace-cmd dump --help shows different options, read the installed help and manpage before copying examples from another host.

2. Choose the input file explicitly

With no -i option, the command reads trace.dat in the current directory. That default is convenient when you are standing beside a newly recorded trace, but it is also an easy distraction: a command can inspect the wrong file simply because another trace.dat is present.

Use -i with an explicit path. The input path may also be the final command-line item, but keeping it beside the option makes a script easier to review:

$ TRACE_FILE='/path/to/trace.dat'
$ test -r "$TRACE_FILE" && printf 'readable: %s\n' "$TRACE_FILE"
readable: /path/to/trace.dat
$ trace-cmd dump --summary -i "$TRACE_FILE"

Replace the placeholder with the real path. The test command only checks readability. It does not prove that the file is a trace-cmd file.

3. Validate the file before inspecting details

Use --validate when you need a yes-or-no check that the input is a valid trace file created by trace-cmd:

$ trace-cmd dump --validate -i "$TRACE_FILE"
File trace.dat is a valid trace-cmd file

The displayed filename can reflect the name recorded or selected by the command. Treat the success message as the checkpoint, not as proof that every event payload is meaningful for your investigation.

A failed validation is useful evidence. For example, this deliberately points at a compressed manpage rather than a trace:

$ trace-cmd dump --validate -i /usr/share/man/man1/trace-cmd-dump.1.gz
  wrong file magic

Do not rename an arbitrary file to trace.dat to make this check pass. Find the original recording or ask the person who supplied it how it was produced. A missing file is a different failure again: the command reports that it cannot open the path.

4. Read the metadata summary

--summary prints the initial format information and a short description of each file section. It is also the default action when no other output option is supplied:

$ trace-cmd dump --summary -i "$TRACE_FILE"

Tracing meta data in file trace.dat:
       [Initial format]
               6       [Version]
               0       [Little endian]
               8       [Bytes in a long]
               4096    [Page size, bytes]
       [Header info, ... bytes]
       [Header event, ... bytes]
       [Ftrace format, ... events]
       [Events format, ... systems]
       ...
       [Flyrecord tracing data]

The ellipses above stand for values that belong to your file, not literal output to paste. The summary can show the trace format version, byte order, page size, event-system count, saved command lines, CPU data and stored options. It is a map of the file's contents, not a decoded event report.

5. Select one metadata section

Use a focused option when the full summary is too broad. These commands remain read-only:

$ trace-cmd dump --systems -i "$TRACE_FILE"
$ trace-cmd dump --clock -i "$TRACE_FILE"
$ trace-cmd dump --cmd-lines -i "$TRACE_FILE"
$ trace-cmd dump --options -i "$TRACE_FILE"
$ trace-cmd dump --flyrecord -i "$TRACE_FILE"

--systems lists each recorded event system and its event count. --clock prints the trace clock. --cmd-lines shows the saved mapping from process IDs to process names. --options lists options stored in the file. --flyrecord shows the offset and size of tracing data for each CPU.

For header work, use --head-page or --head-event. For event format information, use --ftrace-events or --events. The latter prints formats for all events and can be much larger than the summary. Save large output deliberately rather than sending it straight into an interactive terminal:

$ trace-cmd dump --events -i "$TRACE_FILE" > trace-event-formats.txt
$ test -s trace-event-formats.txt && printf 'saved event formats\n'
saved event formats

Shell redirection truncates an existing destination before the command runs. Choose a new filename or copy the old file first if it contains evidence you still need. This changes only the output file, not the trace.

6. Print everything only when you need it

--all prints all metadata from the file. It is useful when exporting a complete description for another investigator, but it can be verbose and may include symbol mappings, process names and other host-specific details. Review the destination and access permissions before saving or sharing it:

$ umask 077
$ trace-cmd dump --all -i "$TRACE_FILE" > trace-metadata.txt
$ wc -l trace-metadata.txt
$ ls -l trace-metadata.txt

This example creates a private local report under the current user's umask. It does not encrypt the report. If the metadata contains sensitive host or workload information, remove the report with your normal approved data-handling process after it is no longer needed. Do not use sudo merely to run trace-cmd dump; elevate only when filesystem permissions genuinely require it.

7. Troubleshoot the common traps

• No such file or directory: check the current directory and the value of TRACE_FILE. Use an absolute path while investigating.
• Wrong file magic: the input is not recognised as a trace-cmd file. Check that it is the original trace, not a compressed archive, text export or unrelated file.
• Unexpectedly small or empty sections: those values describe what was recorded. A file can be valid while containing no tracing data for a particular CPU or section.
• Too much output: return to --summary, then select one section such as --systems or --clock.
• Permission denied: fix access to a copy in a controlled directory if policy allows. Avoid making the original trace world-readable.