Safely Finish an Ftrace Session with trace-cmd reset

Once you have the trace you needed, trace-cmd reset is how you switch Ftrace back off without leaving half-configured tracing state behind on the box. It turns off tracing, clears the trace state it owns and, when requested, shrinks or deletes trace buffer instances.

Allow about five minutes for a simple reset, or longer if you need to identify which buffers may be discarded.

This guide describes the installed Ubuntu package trace-cmd 3.2-1ubuntu2, whose command reports version 3.2.0. The exact kernel tracing support still depends on the running kernel.

1. Check the command before changing tracing

First confirm which executable will run and inspect its reset options. These checks are ordinary, unprivileged commands:

$ command -v trace-cmd
/usr/bin/trace-cmd
$ trace-cmd --version
trace-cmd version 3.2.0 (not-a-git-repo)
$ trace-cmd reset --help
usage:
 trace-cmd reset [-b size][-B buf][-a][-d][-t]

The help output is intentionally brief. The installed manual explains that reset disables the tracer and clears trace state. It also says that data in the ring buffer and the options used are lost after reset.

2. Preserve anything you still need

Checkpoint: stop here if you have not saved the trace data you want to analyse. A reset is not an undoable pause. trace-cmd stop or trace-cmd extract can retrieve data without disabling the tracer, but neither is a substitute for deciding whether the current ring-buffer contents matter.

After extracting or otherwise recording the useful trace, check the tracing status if you need a before-and-after record:

$ trace-cmd stat

The status output varies with the kernel and active configuration. Treat it as an observation, not as a backup. If the tracing setup belongs to another operator or service, coordinate before disabling it.

3. Reset the top-level trace buffer

With no instance-selection option, reset targets the top-level tracing instance. On a host where tracing requires access to the kernel tracing files, run it with elevated privileges:

$ sudo trace-cmd reset

There may be no success message. Check the exit status immediately:

$ printf 'reset exit status: %s\n' "$?"
reset exit status: 0

A zero status means the command completed successfully. It does not restore the discarded ring-buffer data. The practical result is that Ftrace tracing is disabled, so the tracing overhead can be removed from normal workload performance.

4. Target named buffer instances deliberately

Linux tracing can have multiple buffer instances. -B selects a named instance and may be repeated. When any instance-selection option is present, the top-level instance is not reset unless you also give -t:

$ sudo trace-cmd reset -B instance-one
$ printf 'reset exit status: %s\n' "$?"
reset exit status: 0

This resets instance-one without selecting other instances or the top-level buffer. Replace the example name with an instance that exists on your machine. Do not guess a name and infer success from a quiet command; check its exit status and investigate any non-zero result.

To reset every existing instance while leaving the top-level instance alone, use -a:

$ sudo trace-cmd reset -a

To include the top-level instance as well, add -t:

$ sudo trace-cmd reset -t -a

Tip: option order matters. The manual documents -t -a for resetting the top level and all instances, but -a -t -d is invalid because that order would imply deleting the top-level instance. Keep selection and deletion in the order shown by the documentation.

5. Shrink buffers only when reclaiming memory is the goal

Once tracing has expanded a per-CPU ring buffer, the memory remains allocated until you resize it. The -b option changes the per-CPU buffer size in kilobytes:

$ sudo trace-cmd reset -b 1

With no preceding -B, -a or -t, that applies to the top-level instance. A value of 1 is the documented example, not a universal recommendation. Choose a size that suits your next tracing session, and verify the command's exit status before assuming the resize succeeded.

The target is determined by the most recent preceding selection option. For example, this resizes one named instance and then resets another:

$ sudo trace-cmd reset -B instance-one -b 4096 -B instance-two

Here -b 4096 applies to instance-one. The later -B instance-two changes the reset target. Read such commands left to right before running them.

6. Delete instance buffers only after checking twice

Warning: -d deletes the instance buffers selected by the preceding -B or -a. This changes the tracing layout, not just the current data. The top-level instance cannot be deleted.

Delete all non-top-level instances with:

$ sudo trace-cmd reset -a -d

Delete all instance buffers and reset the top level with:

$ sudo trace-cmd reset -t -a -d

There is no reset command that recreates deleted instances with their former contents. If you need the same layout later, record the instance names and configuration before deletion, then recreate it using your normal Ftrace or trace-cmd setup process. Do not run a deletion command as an unreviewed batch step.

7. Verify the finished state

Checkpoint: run a read-only status check after the reset:

$ trace-cmd stat

Confirm that tracing is no longer active and that the expected instances remain. If you need to trace again, start a new session with trace-cmd start or trace-cmd record; reset does not preserve the options from the old session. If reset fails, keep the original data untouched where possible, review the error and permissions, and do not add -d merely to make the command complete.

Done means