List and Use trace-cmd Report Plugin Options

Before you tweak a report's output, check what trace-cmd options already exposes. You will finish with a machine-specific list of the options that trace-cmd report can pass to its loaded plugins, plus a safe way to try one while reading a trace file.

The workflow is read-only: trace-cmd options does not start tracing, change kernel settings or edit a trace. Allow about ten minutes. You need a shell, the trace-cmd package and, for the final example, an existing trace.dat file.

The examples were checked with trace-cmd package version 3.2-1ubuntu2, whose executable reports version 3.2.0. Plugin availability and default values are host-specific.

Tip: if you only need to discover the available settings, complete steps 1 to 3. The report example in step 5 is optional.

1. Confirm the installed command

Check which executable your shell will run and ask it for its 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 package version and the upstream tool version are different pieces of information: record both when comparing output with another machine. Do not use sudo just because a tracing tool is installed. This subcommand only reads plugin information.

2. List the report plugin options

Run the subcommand with no additional arguments:

$ trace-cmd options
  plugin: ftrace
  option: parent
    desc: Print parent of functions for function events
     set: 0
------------
  plugin: ftrace
  option: indent
    desc: Try to show function call indents, based on parents
     set: 1
------------
  plugin: fgraph
  option: tailprint
    desc: Print function name at function exit in function graph
     set: 0
------------
  plugin: fgraph
  option: depth
    desc: Show the depth of each entry
     set: 0
============

Your output may contain a different set of plugins and options. The command examines the plugins used by trace-cmd report, so this is not a general list of every ftrace control exposed by the kernel, and it is not a list of options accepted by trace-cmd record.

Read each block as four fields:

A value of set: 1 is information about the plugin's current setting, not a request to enable anything. The discovery command itself does not alter that value.

3. Turn one block into a report option

trace-cmd report accepts plugin settings with -O. The report manual documents the form plugin:option=value, with the plugin name and value optional in cases where the option can be identified without them. Use the fully qualified form while learning, because it makes the intended target visible:

$ trace-cmd report -O fgraph:tailprint /path/to/trace.dat

Replace /path/to/trace.dat with an actual trace file. This asks the fgraph plugin to print the function name when a function exits. It affects how the report is rendered; it does not rewrite trace.dat and it does not enable function-graph tracing retroactively.

For a boolean option, the value may be omitted according to the report documentation. For example:

$ trace-cmd report -O fgraph:tailprint /path/to/trace.dat
$ trace-cmd report -O fgraph:tailprint=0 /path/to/trace.dat

Tip: use a separate invocation when comparing settings. Do not paste both commands into a script that assumes the second one means "undo" globally: each trace-cmd report process reads the file and applies its own report-time options.

4. Check the result without changing the trace

Send output to a new file if you need to compare two reports. Shell redirection can replace an existing file before trace-cmd has started, so choose a new name:

$ trace-cmd report /path/to/trace.dat > report-default.txt
$ trace-cmd report -O fgraph:tailprint /path/to/trace.dat > report-tailprint.txt
$ wc -l report-default.txt report-tailprint.txt
$ diff -u report-default.txt report-tailprint.txt | sed -n '1,80p'

These commands create or replace the two named report files in the current directory. If either name already contains useful results, stop and choose different names or copy the old file first. The original trace.dat remains untouched.

An empty diff is not automatically a failure. The trace may not contain events for the selected plugin, or the option may not change the presentation of that particular file. Check the command's exit status and inspect the relevant report sections rather than treating a changed line count as proof.

5. Diagnose the common traps

If the trace file cannot be opened, check it without elevated privileges:

$ ls -l /path/to/trace.dat
$ test -r /path/to/trace.dat && echo readable

Warning: only use elevated privileges when the file permissions genuinely require them, and prefer copying the trace to a controlled readable location. Do not make a trace world-readable: trace data can expose process names, paths, command arguments or timing details.

Done means