* doc/Makefile.am (dist_man1_MANS): Add stackprof.1. * doc/stackprof.1: New file.
Co-authored-by: <[email protected]> Signed-off-by: <[email protected]> --- doc/Makefile.am | 2 +- doc/stackprof.1 | 145 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+), 1 deletion(-) create mode 100644 doc/stackprof.1 diff --git a/doc/Makefile.am b/doc/Makefile.am index 35e158b4..c0a3d565 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -20,7 +20,7 @@ EXTRA_DIST = COPYING-GFDL README # Section 1, Executable programs or shell commands # The tools manpages that depend on program prefix (will get eu- prefixed) -dist_man1_MANS=readelf.1 elfclassify.1 srcfiles.1 +dist_man1_MANS=readelf.1 elfclassify.1 srcfiles.1 stackprof.1 # Tools that don't get a program prefix notrans_dist_man1_MANS= debuginfod-find.1 diff --git a/doc/stackprof.1 b/doc/stackprof.1 new file mode 100644 index 00000000..36f72998 --- /dev/null +++ b/doc/stackprof.1 @@ -0,0 +1,145 @@ +.\" Copyright 2026 Red Hat Inc. +.\" Fri 2026-Apr 10 Serhei Makarov <[email protected]> +.\" Contact [email protected] to correct errors or typos + +.de SAMPLE +.br +.RS 0 +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.TH EU-STACKPROF 1 "2026-Apr-10" "elfutils" +.SH "NAME" +eu-stackprof \- collect a multi-process stack profile + +.SH "SYNOPSIS" +.B eu-stackprof \fR[\fB\-v\fR|\fB\-vv\fR|...] [\fB\-\-gmon\fR] [\fB\-o\fR \fB\fIDEST\fR] [\fB\fIOPTION\fR]... [\-\- \fICMD\fR...] + +.SH "DESCRIPTION" + +\fBeu-stackprof\fR collects stack profile data from Linux perf_events, +either systemwide across all processes or targeted to a particular +process (existing PID via \fB\-p\fR or newly launched from provided +command line arguments) and any children forked from it. Superuser +privileges are required to access the perf_events interface. Results +are saved as \fBgmon.out\fR files in the \fIgprof\fR\|(1) format, and +are intended to be useful for statistics collection with profiledb. + +.SH "OPTIONS" + +.TP +\fB\-e\fR \fIEVENT\fR, \fB\-\-event\fR=\fIEVENT\fR +Configure perf_events sampling according to the provided libpfm event +specification (e.g. \fBperf::CPU\-CLOCK:freq=1000\fR). + +.TP +\fB\-\-event\-list\fR +List available libpfm events and exit. + +.TP +\fB\-f, \-\-force\fR +If the output directory for \fB\-\-gmon\fR already contains files +identified by the encountered build-ids, overwrite them with the newly +collected data. + +.TP +\fB\-g, \-\-gmon\fR +Output program counter histograms and callgraphs for each executable +binary encountered during profiling in \fIgprof\fR\|(1)'s +\fBgmon.out\fR format. + +.TP +\fB\-G\fR \fIMETHOD\fR, \-\-hist\-split\fR=\fIMETHOD\fR +Specify the method used to divide the address space into histograms +for \fB\-\-gmon\fR output. METHOD should be one of: +.RS +.TP +\fBnone\fR +Don't split: write one histogram covering the whole address range. +.TP +\fBeven\fR (default) +Split address space into histograms of equal size to satisfy +\fIgprof\fR\|(1)'s scale consistency check. +.TP +\fBflex\fR +Split address space into variable-sized histograms to minimize storage +requirements; result will likely be rejected by the \fIgprof\fR\|(1) +tool, which requires all histograms to have a consistent scale, but +should still be suitable for profiledb. +.RE + +.TP +\fB\-n\fR \fIMAXFRAMES\fR, \fB\-\-maxframes\fR=\fIMAXFRAMES\fR +Upper bound on the number of frames to unwind for each stack sample. +Defaults to 1 if \fB\-\-gmon\fR is enabled, since additional frames +beyond the first are not needed to produce the gprof histogram and +callgraph arc data; defaults to 256 otherwise. + +.TP +\fB\-o\fR \fIDIR\fR, \-\-output\fR=\fIDIR\fR +Directory where to write results when \fB\-\-gmon\fR output is +enabled. Defaults to the current directory. + +.TP +\fB\-v, \-\-verbose\fR +Output additional information. May be given once or multiple times to +increase the granularity, logging each new binary, each stack sample, +or each frame. + +.SH "OUTPUT FORMAT" + +When \fB\-\-gmon\fR output is enabled, \fBeu-stackprof\fR produces the +following files for each executable object observed among the profiled +processes, identified by build-id: + +.TP +\fBgmon.BUILDID.exe\fR + +Symlink to the executable object observed by the profiler. + +.TP +\fBgmon.BUILDID.out\fR + +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 \fIgprof\fR\|(1). + +.TP +\fBgmon.BUILDID.json\fR + +Metadata in JSON format, including the path to the executable object +and libpfm event information. + +.SH "EXAMPLES" + +Profile system-wide; write gmon.out files to current directory: +.SAMPLE +sudo eu-stackprof --gmon +.ESAMPLE + +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: +.SAMPLE +sudo eu-stackprof -vv --gmon -o results/ -p 1211 --force +.ESAMPLE + +Likewise, launch \fBvim\fR and profile it: +.SAMPLE +sudo eu-stackprof --gmon -o results/ --force -- vim test.txt +.ESAMPLE + +Profile system-wide; log one line per stack frame: +.SAMPLE +sudo eu-stackprof -vvv +.ESAMPLE + +.SH "SEE ALSO" +.BR gprof (1), +.BR perf_event_open (2) -- 2.53.0
