EU-STACKPROF(1) General Commands Manual EU-STACKPROF(1)

eu-stackprof - collect a multi-process stack profile

eu-stackprof [-v|-vv|...] [--gmon] [-o DEST] [OPTION]... [-- CMD...]

eu-stackprof collects stack profile data from Linux perf_events, either systemwide across all processes or targeted to a particular process (existing PID via -p or newly launched from provided command line arguments) and any children forked from it. Appropriate privileges are needed to access the perf_events interface, either globally or for a particular targeted process; refer to perf_event_open(2) section "Arguments" for a summary of the privilege requirements.

When the --gmon option is used, results are saved as gmon.out files in the gprof(1) format. These are intended to be useful for statistics collection with profiledb.

When the --gmon option is not used, eu-stackprof will collect and print basic statistics about the profile data to standard error.

Configure perf_events sampling according to the provided libpfm event specification (e.g. perf::CPU-CLOCK:freq=1000).
List available libpfm events and exit.
If the output directory for --gmon already contains files identified by the encountered build-ids, overwrite them with the newly collected data.
Output program counter histograms and callgraphs for each executable binary encountered during profiling in gprof(1)'s gmon.out format.
Specify the method used to divide the address space into histograms for --gmon output. METHOD should be one of:
Don't split: write one histogram covering the whole address range.
Split address space into histograms of equal size to satisfy gprof(1)'s scale consistency check.
Split address space into variable-sized histograms to minimize storage requirements; result will likely be rejected by the gprof(1) tool, which requires all histograms to have a consistent scale, but should still be suitable for profiledb.
-?, --help
Print a short list of options.
Upper bound on the number of frames to unwind for each stack sample. Defaults to 1 if --gmon is enabled, since additional frames beyond the first are not needed to produce the gprof histogram and callgraph arc data; defaults to 256 otherwise.
Directory where to write results when --gmon output is enabled. Defaults to the current directory.
Restrict the profile to process PID and its future children.
Output additional information. May be given once or multiple times to increase the granularity, logging each new binary, each stack sample, or each frame.
Print program version.

When --gmon output is enabled, eu-stackprof produces the following files for each executable object observed among the profiled processes, identified by build-id:

Symlink to the executable object observed by the profiler.

Contains a histogram of program counters and a table of callgraph arcs (observed from the top 2 frames of the stacktrace). Same format as produced by the gprof infrastructure and consumed by gprof(1).

Metadata in JSON format, including the path to the executable object and libpfm event information.

Profile system-wide; write gmon.out files to current directory: 

sudo eu-stackprof --gmon

Profile PID 1211 and children forked from it; log one line per stack sample; write gmon.out files to results/, replacing any already-existing files with the same build-ids: 

sudo eu-stackprof -vv --gmon -o results/ -p 1211 --force

Likewise, launch vim and profile it: 

sudo eu-stackprof --gmon -o results/ --force -- vim test.txt

Profile system-wide; log one line per stack frame: 

sudo eu-stackprof -vvv

Report bugs to <elfutils-devel@sourceware.org> or https://sourceware.org/bugzilla/.

gprof(1), perf_event_open(2)

2026-Apr-10 elfutils