EU-STACKPROF(1)

📦 version 0.197, in arch rolling, centos-stream 10, fedora 43, fedora 44, ubuntu stonking

💖 eu-stackprof(1) 💖

okay bestie, sit DOWN, because this one is literally the girlboss of stack profilers. this is eu-stackprof from the elfutils squad, and she's here to collect a multi-process stack profile for you. no cap. 🎀

✨ SYNOPSIS ✨

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

🌸 DESCRIPTION 🌸

so basically, eu-stackprof collects stack profile data from Linux perf_events. she can do it systemwide across literally every process, or she can lock in on one specific process — either an existing one you hand her with -p, or a brand new one she launches from the command line arguments you give her — plus any children forked from it. yes, the babies count too. 🫶

to get at the perf_events interface you need the right privileges, either globally or for the particular targeted process. go check out perf_event_open(2), section "Arguments", for the whole rundown on privilege requirements. it's giving homework but it's important. 📚

when you use the --gmon option, the results get saved as gmon.out files in the gprof(1) format. those are meant to be useful for collecting statistics with profiledb. iconic.

when you DON'T use --gmon, eu-stackprof just collects and prints basic stats about the profile data to standard error. lowkey chill of her. 💅

👑 OPTIONS 👑

  • -e EVENT, --event=EVENT — configure the perf_events sampling according to the libpfm event spec you give her (like, say, perf::CPU-CLOCK:freq=1000). yes ma'am, specify the vibe. ✨
  • --event-list — list all the available libpfm events and dip. window shopping, but for events. 🛍️
  • -f, --force — if the output directory for --gmon already has files matching the build-ids she ran into, just overwrite them with the freshly collected data. no hesitation, no mercy. 💀
  • -g, --gmon — output program counter histograms AND callgraphs for every executable binary encountered during profiling, in gprof(1)'s gmon.out format. the whole menu. 🍓
  • -G METHOD, --hist-split=METHOD — pick the method used to divide the address space into histograms for the --gmon output. METHOD should be one of:
    • none — don't split at all: write one histogram covering the whole address range. one girl, one histogram. 💅
    • even (default) — split the address space into histograms of equal size, so that gprof(1)'s scale consistency check is satisfied. she's a rule follower, we love that. ✨
    • flex — split the address space into variable-sized histograms to minimize storage requirements. the result will likely be rejected by the gprof(1) tool, since it requires all histograms to have a consistent scale — but it should still be suitable for profiledb. chaotic good energy, honestly. 🙈
  • -?, --help — print a short list of options. the lil cheat sheet. 🎀
  • -n MAXFRAMES, --maxframes=MAXFRAMES — upper bound on how many frames to unwind for each stack sample. defaults to 1 if --gmon is enabled, because frames beyond the first aren't needed to produce the gprof histogram and callgraph arc data; defaults to 256 otherwise. know your limits bestie. 🦋
  • -o DEST, --output=DEST — the directory where results get written when --gmon output is enabled. defaults to the current directory. home sweet home. 🌈
  • -p PID, --pid=PID — restrict the profile to process PID and its future children. just them, nobody else. 👑
  • -v, --verbose — output additional info. you can give this once or multiple times to crank up the granularity, logging each new binary, each stack sample, or each frame. more vs = more tea. 🍵
  • -V, --version — print program version. the origin story. ⭐

💜 OUTPUT FORMAT 💜

when --gmon output is enabled, eu-stackprof produces the following files for each executable object she observed among the profiled processes, identified by build-id:

  • gmon.BUILDID.exe — a symlink to the executable object observed by the profiler. cute little pointer. 🫶
  • 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). the real deal. 🔥
  • gmon.BUILDID.json — metadata in JSON format, including the path to the executable object and libpfm event information. receipts. 🧾

🌟 EXAMPLES 🌟

profile system-wide; write gmon.out files to the 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 😭

found a bug? spill the tea to <elfutils-devel@sourceware.org> or hit up https://sourceware.org/bugzilla/. they wanna hear it fr fr.

🦋 SEE ALSO 🦋

gprof(1), perf_event_open(2)

okay that's the whole page bestie, go forth and profile 💖 this was brought to you by elfutils, dated 2026-Apr-10. periodt. 💅✨

📦 where this page comes from