Read ftrace's Live State with trace-cmd stat

trace-cmd stat gives you a full read of a host's ftrace state without starting, stopping or resetting anything. The output can show configured instances, an active tracer, enabled events, filters, buffer sizes, the trace clock, CPU masks, probes and the ftrace error log.

Allow about ten minutes. You need a shell and the trace-cmd package. The examples below use trace-cmd 3.2.0 from Ubuntu package version 3.2-1ubuntu2. Reading ftrace usually requires elevated privileges on the host, so have sudo available if the unprivileged check is refused.

1. Confirm the Installed Command

Check which executable and package version you are running. These ordinary commands 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 program's own version are related but are not the same string. If your distribution reports another version, use trace-cmd stat --help and the installed manual page as the local contract.

$ trace-cmd stat [OPTIONS]

2. Run the Basic Status Query

Try the query as your current user first. It does not enable an event or alter a buffer:

$ trace-cmd stat
trace-cmd: Permission denied
  opendir

This failure is about access to the kernel tracing directories, not proof that tracing is disabled. On this host, the unprivileged command cannot open the relevant ftrace directory. Run the same read-only query with sudo when your account is permitted to do so:

$ sudo trace-cmd stat
Instances:

Events:
 All disabled

Buffer size in kilobytes (per cpu):
   1410

Buffer total size in kilobytes:
   11280

Tracing is enabled

Error reading stack tracer status

Your output will reflect the host at that moment. An empty Instances: section means no configured ftrace instance was listed, not that the top-level tracing directory is absent. Likewise, All disabled describes event enablement; it is separate from the line saying whether tracing is enabled.

3. Read the Parts That Are Present

trace-cmd stat reports several kinds of state, but it deliberately omits some values when they sit at their defaults. Use these interpretations while reading the output:

• Tracer. Appears when a tracer such as function_graph is active. No tracer line means no non-default tracer was displayed.
• Events and Event filters. Show enabled events and filters applied to them.
• Function filters and Graph functions. Show restrictions used by function tracers and the functions selected for graphing.
• Buffers. Show an expanded trace buffer size. The manual says compressed, unused buffers are not displayed in this section.
• Trace clock. Appears when the clock is not the default local.
• Trace CPU mask. Appears when tracing is limited to some, rather than all, available CPUs.
• Trace max latency. Appears when its value is not zero.
• Kprobes and Uprobes. Show probes defined for tracing.
• Error log. Contains the ftrace error log when the kernel exposes one.

The absence of a section is often meaningful. Do not turn a missing default-valued line into an invented value, and do not treat a displayed error such as Error reading stack tracer status as a command that changed tracing: it reports a read problem for that part of the status query.

4. Inspect One Tracing Instance

Modern ftrace can have named instances below the top-level tracing directory. To ask for one instance, pass its buffer name with -B:

$ sudo trace-cmd stat -B INSTANCE_NAME

Replace INSTANCE_NAME with an instance name that exists on your host. Do not guess it: get names from the Instances: part of the general status output or from the tracing administration used by your system. Repeat the option for several instances:

$ sudo trace-cmd stat -B INSTANCE_A -B INSTANCE_B

-B asks for the named instance status; it does not create an instance. If you also want the top-level tracing directory in that same query, add -t:

$ sudo trace-cmd stat -t -B INSTANCE_NAME

5. Show Every Option Value

For a more detailed snapshot, add -o:

$ sudo trace-cmd stat -o
$ sudo trace-cmd stat -o -B INSTANCE_NAME

This asks trace-cmd to display all tracing options together with their values. Options whose names start with no are disabled. The result can be much longer than the default report, so save it when comparing two known points in time:

$ sudo trace-cmd stat -o > /tmp/trace-cmd-stat.txt
$ sed -n '1,80p' /tmp/trace-cmd-stat.txt

The file here is a temporary diagnostic snapshot, not persistent tracing configuration. Remove it when it is no longer needed if it contains host-specific event or probe names.

6. Diagnose Without Changing State

If the command fails, keep the diagnosis read-only. Check the executable, retry with the privilege required by the host, and compare the requested instance name with the names actually reported. A non-zero result or a partial report is a reason to investigate access to the kernel tracing interface, not a reason to run trace-cmd reset.

If you are investigating another operator's trace session, record the time and the exact command line. Status is live: events, filters, CPU masks and buffers can change between two queries. If a service is actively tracing, do not stop it merely to make your output cleaner. Ask the service owner before making any state-changing trace-cmd request.

There is no undo command for the examples in this guide, because they only read status and, in the final example, write a text snapshot under /tmp. To discard that snapshot, use:

$ rm -- /tmp/trace-cmd-stat.txt