Measure Kernel Stack Depth with trace-cmd stack

trace-cmd stack watches how deep the kernel's call stack goes and remembers the worst case it has seen. It is not a trace-file command: it does not create trace.dat and it does not show a history of every call, only the largest stack usage since the measurement started or was last reset. The examples use trace-cmd 3.2.0 from Ubuntu package version 3.2-1ubuntu2. Allow about ten minutes, plus a short maintenance window if you need to start tracing on a busy host.

1. Confirm the installed command

Check the binary and version before copying examples into a script:

$ command -v trace-cmd
/usr/bin/trace-cmd
$ trace-cmd --version
trace-cmd version 3.2.0 (not-a-git-repo)

The package version and the program version are separate pieces of information. On this machine, dpkg-query -W -f='${Package} ${Version}\n' trace-cmd reports trace-cmd 3.2-1ubuntu2. Your distribution may package another release, so check the local help if an option behaves differently.

2. Read the current maximum

With no option, the command displays the current stack result:

$ trace-cmd stack
Max stack found: 0 bytes

The exact line depends on the kernel and on whether the tracer has observed any work. Treat the output as a measurement, not a permanent property of the machine: a low value can simply mean the workload has not exercised the deeper paths yet.

The command reads the kernel tracing interface, commonly exposed below /sys/kernel/tracing. If you see Permission denied, that is an access problem, not evidence that the maximum is zero:

$ trace-cmd stack
trace-cmd: Permission denied
  reading to '/sys/kernel/tracing/stack_trace'
(stack tracer not running)

Do not parse that parenthesised message as a successful measurement. First establish whether your account can read the tracing filesystem. If your security policy permits it, rerun the same read-only command with elevation:

$ sudo trace-cmd stack
$ printf '%s\n' "$?"
0

The output and status vary with the kernel, permissions and tracer state, so check the status immediately after the command. If elevated access is not appropriate, ask the system owner for a read-only tracing capability instead of weakening the host policy.

3. Start a bounded measurement

Start the tracer, exercise only the workload you intend to measure, then stop it:

$ sudo trace-cmd stack --start
$ ./the-command-you-need-to-measure
$ sudo trace-cmd stack --stop
Max stack found: 4096 bytes

--start enables the stack tracer: while it is enabled, each function call is checked and a new maximum recorded when found. --stop disables it and prints the maximum found since the start. Replace ./the-command-you-need-to-measure with a real, bounded command, not a placeholder left unchanged.

Keep the privilege level consistent. The workload does not need to run as root just because the tracing control commands do. If the workload itself needs a service account, run it as that account and use the smallest privilege needed for the tracing operations themselves.

$ sudo trace-cmd stack
Max stack found: 4096 bytes

If a stop command fails, do not assume the tracer stopped. Check the state with a read and resolve the access issue before starting another measurement.

4. Reset the counter before a new comparison

The maximum is cumulative for the current stack-tracer state. Use --reset when you need a fresh baseline:

$ sudo trace-cmd stack --reset
$ sudo trace-cmd stack
Max stack found: 0 bytes

Resetting discards the current maximum. It does not disable tracing, preserve the old result, or write a trace file. Save any value you need before resetting:

$ before=$(sudo trace-cmd stack)
$ printf 'baseline: %s\n' "$before"
$ sudo trace-cmd stack --reset

5. Use verbosity only while diagnosing

--verbose sets trace-cmd's log level. It accepts none, critical, error, warning, info, debug or all, as well as the numeric identifiers 0 through 6. Provide the option without a level and the default is info.

$ sudo trace-cmd stack --verbose=debug
$ printf '%s\n' "$?"
0

Use extra logging for a failed read, start or stop, then remove it from routine scripts. Verbose diagnostics can be noisy, and the output format is not a stable data interface for monitoring.