Check Linux Trace Event Formats with trace-cmd

trace-cmd check-events answers a specific question fast: can this host actually parse its own kernel trace event formats. Allow about five minutes for a first check, plus more time if it turns up something to investigate.

1. Confirm the installed command

This guide describes the trace-cmd package installed on the machine used for these examples: Ubuntu package trace-cmd 3.2-1ubuntu2, reporting upstream version 3.2.0. It's part of trace-cmd's Ftrace tooling, so run it on the Linux host whose event formats you actually want to inspect:

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

The command reads the local system's trace event formats. It does not record a trace, change enabled events, clear buffers, or write a trace.dat file.

2. Run the normal check

Start with the default invocation. It parses the format strings for every event visible on the local system and succeeds when they all parse correctly:

$ trace-cmd check-events
$ echo $?
0

A successful run can be completely silent. The useful result is the exit status, not a summary of every event:

• 0 means clean. This invocation completed without finding an unparseable event format.
• Non-zero means dig further. You'll need the diagnostic output and the exact environment for the next steps.

3. Repeat without loading plugins

The default check loads trace-cmd plugins, which can decode event formats that contain internal kernel function references. That normal result answers the practical question: can this host parse its events with its installed support. To test the raw event formats without plugin loading, add -N:

$ trace-cmd check-events -N
$ echo $?
0

Compare the two runs rather than treating -N as a better default. If the normal command succeeds but the no-plugin one fails, a plugin is contributing to the result, useful evidence that the event format may reference something only a plugin can decode, and the host may need one, or a change to the event format.

Run both modes from the same shell and record the installed package version. Plugin directories, environment variables, kernel version and event availability all vary between hosts, so a pass or failure on one machine proves nothing about another.

4. Increase or reduce diagnostic detail

Use --verbose when the default output doesn't explain a failure. It accepts a level name or its number: none/0, critical/1, error/2, warning/3, info/4, debug/5, all/6. A selected level includes that level and every less chatty one before it; with no value given, it defaults to info.

For a readable first pass, request warnings:

$ trace-cmd check-events --verbose=warning
$ echo $?
0

If that's not enough, try --verbose=debug, then --verbose=all only if you still need it. Keep the output with the version and command line when reporting a problem.

$ trace-cmd check-events --verbose=not-a-level
  invalid verbose level not-a-level
$ echo $?
255

5. Investigate a failed check without changing tracing

Capture the evidence from the same host first:

$ trace-cmd version
$ trace-cmd check-events --verbose=debug 2>check-events.err
$ status=$?
$ printf 'exit status: %s\n' "$status"
$ sed -n '1,160p' check-events.err

That redirection creates or replaces check-events.err, so pick a disposable path or back it up if the filename matters. The check itself is read-only for tracing configuration, but the diagnostic capture can still overwrite a local file.

Then compare against a no-plugin run:

$ trace-cmd check-events -N --verbose=debug 2>check-events-no-plugins.err
$ printf 'exit status: %s\n' "$?"
$ diff -u check-events-no-plugins.err check-events.err

An error in both runs points at the local event format or the core parser. A difference between them points at plugin handling. Check the event source and plugin installation match before drawing a conclusion.

6. Clean up captured diagnostics

Once you've reported or kept the evidence, remove only the files you created for this investigation:

$ rm -- check-events.err check-events-no-plugins.err