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

# [NAME](#NAME)

eu-stackprof - collect a multi-process stack profile

# [SYNOPSIS](#SYNOPSIS)

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

# [DESCRIPTION](#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)](/man/os/elfutils/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)](/man/os/elfutils/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](#OPTIONS)

[**-e** *EVENT*, **--event**=*EVENT*](#e)

Configure perf\_events sampling according to the provided libpfm event specification (e.g. **perf::CPU-CLOCK:freq=1000**).

[**--event-list**](#event)

List available libpfm events and exit.

[**-f, --force**](#f,)

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

[**-g, --gmon**](#g,)

Output program counter histograms and callgraphs for each executable binary encountered during profiling in [*gprof*(1)](/man/os/elfutils/gprof.1)'s **gmon.out** format.

[**-G** *METHOD*, **--hist-split**=*METHOD*](#G)

Specify the method used to divide the address space into histograms for **--gmon** output. METHOD should be one of:

[**none**](#none)

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

[**even** (default)](#even)

Split address space into histograms of equal size to satisfy [*gprof*(1)](/man/os/elfutils/gprof.1)'s scale consistency check.

[**flex**](#flex)

Split address space into variable-sized histograms to minimize storage requirements; result will likely be rejected by the [*gprof*(1)](/man/os/elfutils/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*](#n)

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*](#o)

Directory where to write results when **--gmon** output is enabled. Defaults to the current directory.

[**-p** *PID*, **--pid**=*PID*](#p)

Restrict the profile to process *PID* and its future children.

[**-v, --verbose**](#v,)

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**](#V,)

Print program version.

# [OUTPUT FORMAT](#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**](#gmon.BUILDID.exe)

Symlink to the executable object observed by the profiler.

[**gmon.BUILDID.out**](#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)](/man/os/elfutils/gprof.1).

[**gmon.BUILDID.json**](#gmon.BUILDID.json)

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

# [EXAMPLES](#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](#REPORTING_BUGS)

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

# [SEE ALSO](#SEE_ALSO)

[**gprof**(1)](/man/os/elfutils/gprof.1), [**perf\_event\_open**(2)](/man/os/elfutils/perf_event_open.2)

2026-Apr-10 elfutils

---

Document: eu-stackprof(1) from elfutils 0.196-r1 (Chainguard OS)
Source: https://sourceware.org/git/elfutils.git