Inspect a trace.dat File with trace-cmd dump

trace-cmd dump checks a trace file, prints its metadata summary, and lets you narrow the output to the part you actually need. Allow about ten minutes for a first look.

The command reads a file created by trace-cmd record; it does not start tracing, reset the kernel, or alter the input file. You need a shell, the trace-cmd package, and a trace file 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 need no 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 this operation trace-cmd dump, not a separate trace-cmd-dump executable. If trace-cmd dump --help shows different options on your machine, 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 handy when you are standing beside a freshly recorded trace, but it is also an easy way to inspect the wrong file simply because another trace.dat happens to be nearby.

$ 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 input path may also work as the final command-line item, but keeping it beside -i makes a script easier to review later. Note that test above only checks readability; it does not prove the file is actually a trace-cmd file.

3. Validate the file before inspecting details

Use --validate when you need a plain yes-or-no answer: is this input 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, so treat the success message as your checkpoint, not as proof every event payload is meaningful for your investigation. A failed validation is useful evidence in its own right. 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

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 you pass no other output option:

$ 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: 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 much. These commands stay 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 the 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 every event 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

6. Print everything only when you need it

--all prints all metadata from the file. It is useful when you are exporting a complete description for another investigator, but it can be verbose and may include symbol mappings, process names and other host-specific details:

$ 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 anything. If the metadata contains sensitive host or workload information, remove the report through your normal approved data-handling process once it is no longer needed. Do not use sudo merely to run trace-cmd dump: elevate only when filesystem permissions genuinely require it.

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 it is the original trace, not a compressed archive, text export or unrelated file.
• Unexpectedly small or empty sections: those values describe what was actually recorded. A file can be valid while containing no tracing data for a particular CPU or section.
• Too much output: go back to --summary, then select one section such as --systems or --clock.
• Permission denied: fix access on a copy in a controlled directory if policy allows it. Avoid making the original trace world-readable just to get past this.