---
name: "eu-stackprof"
section: "1"
platform: "linux"
package: "elfutils"
version: "0.197-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/eu-stackprof"
---

# eu-stackprof(1)

collect a multi-process stack profile

## 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)](/perf_event_open/2.md) 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)](/gprof/1.md) 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)](/gprof/1.md)'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)](/gprof/1.md)'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)](/gprof/1.md) 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)](/gprof/1.md).

- **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)](/gprof/1.md), [**perf\_event\_open**(2)](/perf_event_open/2.md)