Capture a Focused Ftrace Window with trace-cmd start

trace-cmd start switches on Ftrace for one chosen event without writing a trace.dat file or waiting on a recording thread. Use it when tracing needs to be armed before a specific action, then captured and switched off straight after. This guide walks through choosing an event, starting the tracer, reproducing the behaviour, stopping the buffer, extracting the result and resetting tracing when you are done.

Before you start

You need the trace-cmd package, a kernel with Ftrace available, and root privileges for the tracing commands. The installed package used for these examples is Ubuntu's trace-cmd 3.2-1ubuntu2, reporting upstream version 3.2.0. Kernel event names and available tracers still depend on the running kernel.

Allow about five minutes for a first capture. Have one reproducible action ready, and choose a narrow event set: Ftrace can generate a great deal of data, so broad function tracing is a poor starting point on a busy machine.

1. Pick the Event to Trace

List what the running kernel actually exposes before you copy an example event name. This is a read-only check and does not touch tracing state:

trace-cmd list -e

Look for an event that describes the behaviour you are investigating. The examples below use sched_switch, but replace it with an event shown by your own machine. If this command reports permission denied while reading /sys/kernel/tracing/available_events, fix access to the tracing filesystem or run it with the privileges used for the capture.

2. Start Tracing

Start the tracer with the selected event. This changes kernel tracing state and must run as root, or through sudo where your system permits it:

sudo trace-cmd start -e sched_switch

The command enables tracing and returns without creating trace.dat. It also does not wait for a recording thread, which is the practical distinction from trace-cmd record. If the command fails, do not continue to the reproduction step: check that Ftrace is available and that the event name came from trace-cmd list -e.

You can select more than one event by repeating -e. A tracer plugin can be selected with -p, and -P PID limits events to a process ID where the kernel supports that filtering. Keep the first run small so the result is easier to interpret.

3. Reproduce the Behaviour

Run only the action that should appear in the trace. Substitute a safe, real command for the placeholder below; the action is ordinary user work, but the trace stays active until you stop it:

# Replace this with the action you are investigating.
/path/to/reproduce-the-problem

Tip: Do not leave tracing enabled while you investigate unrelated work. The ring buffer is finite, so noisy activity can overwrite the useful beginning of the capture. If you need a command to run asynchronously, trace-cmd start has a start-only --fork option: it affects the command form only when start is also executing a command, and it is not a general background switch for an already-running shell.

4. Stop the Buffer and Extract It

Stop Ftrace from writing new events to the ring buffer:

sudo trace-cmd stop

Stopping preserves the captured data, but it does not remove all tracing overhead: the tracer configuration remains active until you reset it. Extract the stopped buffer into a file you can inspect later:

trace_file=/tmp/trace-cmd-window.dat
sudo trace-cmd extract -o "$trace_file"

The -o option belongs to extract, not start. The start command accepts the recording options relevant to enabling Ftrace, but excludes recording-specific -s, -o, -N, and -t options. Extraction reads the kernel ring buffer and creates the trace.dat-format file.

5. Inspect the Result

Use the report command to read the extracted file. This does not alter the capture:

trace-cmd report -i /tmp/trace-cmd-window.dat | sed -n '1,80p'

Expect a human-readable event report when the file contains data. An empty or unexpectedly short report usually means one of four things: the selected event did not occur, the action was too short, the buffer wrapped before you stopped it, or the start command did not succeed. Repeat the event-list check and capture rather than guessing at event names.

6. Reset Tracing When You Are Finished

Reset Ftrace after you have extracted anything you need:

sudo trace-cmd reset

Warning: This disables Ftrace and clears the ring-buffer data and options recorded by the tracing session. Treat it as destructive to the in-kernel capture. Run it only after extraction or after deciding that the data is no longer needed. The extracted file in /tmp is separate from that ring buffer, so it remains available for reporting.

Recovery: If you stopped tracing but have not extracted the data, run sudo trace-cmd extract -o /tmp/trace-cmd-window.dat before resetting. If a capture is still active and you need to abandon it, sudo trace-cmd reset is the recovery command, with the deliberate cost of losing the in-kernel data.

Common traps

• Confusing stop and reset. stop stops ring-buffer updates but leaves tracing overhead; reset disables tracing and loses the in-kernel capture.
• Expecting a file from start. start deliberately does not create trace.dat. Use extract after stop.
• Using an unavailable event. Event names are kernel-specific. Confirm them with trace-cmd list -e on the target machine.
• Tracing too broadly. Options such as function tracing can add substantial volume and overhead. Begin with one event and expand only when the evidence requires it.
• Forgetting buffer instances. If you use named buffers, the -B, -a, and -t choices on stop and extract determine which instances are handled. Keep the default top-level buffer for a first session.

Done means

• Event confirmed. The selected event was confirmed with trace-cmd list -e.
• Tracing started. trace-cmd start completed before the reproduction action.
• Recording stopped. trace-cmd stop completed before extraction.
• Capture readable. trace-cmd report -i /tmp/trace-cmd-window.dat can read the extracted capture.
• Tracing reset. sudo trace-cmd reset has restored normal tracing state.