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)