doc/stackprof.1: Add a basic man page

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1ced7858e7222074b64e769fc740ab7a1decf7dc..8b8e55e59463c1ee1c858567b6f91b2f3a9707cb 100644 (file)
--- 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 (file)
index 0000000..12ba99f
--- /dev/null
+++ b/doc/stackprof.1
@@ -0,0 +1,137 @@
+.\" Copyright 2026 Red Hat Inc.
+.\" Fri 2026-Apr 10 Serhei Makarov <serhei@serhei.io>
+.\" Contact elfutils-devel@sourceware.org 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 [\fB\-v\fR|\fB\-vv\fR|...] [\fB\-\-gmon\fR] [\fB\-o\fR \fB\fIDEST\fP] [\fB\fIOPTION\fP]...
+
+.SH "DESCRIPTION"
+
+\fBeu-stackprof\fR collects stack profile data from Linux perf_events,
+either systemwide across all processes or targeted to a particular
+process and any children forked from it. 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,
+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
+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 already-existing
+files:
+.SAMPLE
+eu-stackprof -vv --gmon -o results/ -p 1211 --force
+.ESAMPLE
+
+Profile system-wide; log one line per stack frame:
+.SAMPLE
+eu-stackprof -vvv
+.ESAMPLE
+
+.SH "SEE ALSO"
+.BR gprof (1),
+.BR perf_event_open (2)