eu-stackprof - Man Page

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.

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

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.

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)