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




NAME
       eu-stackprof - collect a multi-process stack profile


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


DESCRIPTION
       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.


OPTIONS
       -e EVENT, --event=EVENT
              Configure perf_events sampling according to the provided libpfm
              event specification (e.g. perf::CPU-CLOCK:freq=1000).


       --event-list
              List available libpfm events and exit.


       -f, --force
              If the output directory for --gmon already contains files
              identified by the encountered build-ids, overwrite them with the
              newly collected data.


       -g, --gmon
              Output program counter histograms and callgraphs for each
              executable binary encountered during profiling in gprof(1)'s
              gmon.out format.


       -G METHOD, --hist-split=METHOD
              Specify the method used to divide the address space into
              histograms for --gmon output. METHOD should be one of:

              none   Don't split: write one histogram covering the whole
                     address range.

              even (default)
                     Split address space into histograms of equal size to
                     satisfy gprof(1)'s scale consistency check.

              flex   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.


       -n MAXFRAMES, --maxframes=MAXFRAMES
              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.


       -o DEST, --output=DEST
              Directory where to write results when --gmon output is enabled.
              Defaults to the current directory.


       -p PID, --pid=PID
              Restrict the profile to process PID and its future children.


       -v, --verbose
              Output additional information. May be given once or multiple
              times to increase the granularity, logging each new binary, each
              stack sample, or each frame.


       -V, --version
              Print program version.


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


       gmon.BUILDID.exe

              Symlink to the executable object observed by the profiler.


       gmon.BUILDID.out

              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).


       gmon.BUILDID.json

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


EXAMPLES
       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


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


SEE ALSO
       gprof(1), perf_event_open(2)

elfutils                          2026-Apr-10                  EU-STACKPROF(1)