Inspect Ftrace Events and Tracers with trace-cmd list

trace-cmd list tells you what a kernel's Ftrace setup actually offers before you commit to tracing anything. That covers event systems, individual events, fields, filters, tracers, plugin files, buffer instances, clocks and compression support.

Safety boundary: do not substitute trace-cmd start, record or reset while following these steps. Those commands change tracing state; list only reports what is available.

1. Confirm the installed command

Check which executable runs and note its version, no privileges required:

$ 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 subcommand is trace-cmd list, not a separate executable called trace-cmd-list: the installed manual just uses that name because it documents this subcommand.

Checkpoint: if command -v finds nothing, install the package through your normal system-management process or fix PATH. Do not copy an executable in from an unrelated host.

2. Pull the complete inventory

With no option at all, the command prints every plugin, event system, event and Ftrace option configured on the machine:

$ trace-cmd list

That can be a lot of output. Save it only when you have a specific reason, and pick a new filename rather than overwriting an existing report:

$ trace-cmd list > trace-cmd-list.txt
$ test -s trace-cmd-list.txt && echo "inventory written"
inventory written

Shell redirection truncates the destination before trace-cmd even runs, so if the old report matters, copy it first or pick a new name. Deleting an old report is your call, not part of this guide.

3. Find event systems and matching events

Start with event systems when you do not already know the exact event name:

$ trace-cmd list -s

Output is entirely host-specific. An event system is the prefix before the colon in an event name, such as sched in sched:sched_switch. List local events with -e:

$ trace-cmd list -e '^sched:.*'

The argument is an optional regular expression using the system's regcomp(3) syntax; quote it so the shell leaves special characters alone. No output can just mean nothing matched, but a line like Permission denied means tracefs itself could not be read, which is a different problem.

For one specific event, narrow the expression:

$ trace-cmd list -e '^sched:sched_switch$'

Checkpoint: a match gives you an event name. If you need more detail than that, keep the same expression and add the options below instead of guessing field names.

4. Inspect fields, filters and triggers

Add -F to show the fields for whatever -e selected:

$ trace-cmd list -e '^sched:sched_switch$' -F

Add --full alongside -F when you also want the event's print fmt:

$ trace-cmd list -e '^sched:sched_switch$' -F --full

None of that enables the event; it only describes the interface. To see filters on the selected events, use -l; for triggers, use -R:

$ trace-cmd list -e '^sched:sched_switch$' -l
$ trace-cmd list -e '^sched:sched_switch$' -R

An empty filter or trigger listing is not automatically an error, it may simply mean none are configured. Rerun the plain event query first and confirm the event itself shows up before you worry about a blank result here.

5. Inspect tracers, functions and Ftrace options

List the tracers available on this system with -t (the legacy -p spelling does the same thing):

$ trace-cmd list -t
$ trace-cmd list -p

List traceable or filterable functions with -f, which takes the same style of regular-expression argument:

$ trace-cmd list -f '^sched_.*'

Use -o for the Ftrace options configured locally:

$ trace-cmd list -o

All of these are discovery only. Seeing a tracer or function listed does not switch it on; enabling tracing is a separate operation with its own operational risk.

6. Check plugins, buffers, clocks and compression

A handful of useful inventories are not event queries at all:

$ trace-cmd list -P    # plugin files used by trace-cmd report
$ trace-cmd list -O    # plugin options for trace-cmd report -O
$ trace-cmd list -B    # defined buffer instances
$ trace-cmd list -C    # clocks usable with trace-cmd record -C
$ trace-cmd list -c    # available trace-file compression algorithms

For -C, the clock shown in square brackets is the one currently active, worth checking before you pick a -C value for a later record command. -c can work even when event data is off-limits, because it reports supported compression algorithms rather than reading the events directory. This installation, for example, reports:

Supported compression algorithms:
        zstd, 1.5.5

Do not read a working compression query as proof that tracefs access in general is healthy. Test the specific inventory you actually need.

7. Diagnose permission and missing-tracefs errors

On a restricted host, a command that reads events or tracers can fail like this:

trace-cmd: Permission denied
Can not read events directory

That is not the same thing as "there are no events". Check the tracing filesystem mount and its permissions without changing anything:

$ findmnt /sys/kernel/tracing
$ namei -l /sys/kernel/tracing/available_events
$ test -r /sys/kernel/tracing/available_events && echo readable || echo not-readable

If your administrator has explicitly signed off on it, retry the read with elevated privileges:

$ sudo trace-cmd list -e '^sched:.*'

Warning: do not reach for sudo to paper over a missing mount. If findmnt shows nothing, ask the administrator how tracing is provided on that host. Do not mount tracefs, change ownership, loosen permissions or touch container settings just to make an inventory command pass: those changes affect system observability and security, and they are well outside a read-only inspection.

If a narrow expression comes back empty with no diagnostic at all, try a broader query such as trace-cmd list -s. If that works, refine the regular expression. If every tracefs-backed query fails outright, sort out access or mount policy before you try to interpret any of the results.

Done means