GPROFNG-COLLECT-APP(1)

📦
version 2.47 · 15 versions
, in ubuntu stonking

💖 GPROFNG-COLLECT-APP 💖

okay bestie, this is the gprofng-collect-app page from the gprofng family of User Commands — it's the one that goes out and gets the data for you. she's the collector. the gatherer. the main character who does the fieldwork so the display tools can serve looks later. 🎀

✨ NAME ✨

gprofng-collect-app — collect performance data for the target application 🫶

🌸 SYNOPSIS 🌸

gprofng collect app [option(s)] target [target-option(s)]

🦋 DESCRIPTION 🦋

so like. this collects performance data on the target program. not just Program Counter (PC) sampling — she ALSO does hardware event counters and a whole bunch of tracing options. versatile queen. 👑

for example, this command collects performance data for an executable called a.out and stores all that data in an experiment directory named example.er:

$ gprofng collect app -o example.er ./a.out

literally that's it. one line and you're collecting. periodt. ✨

💅 OPTIONS 💅

  • --version — prints the version number and dips. that's the whole job.
  • --help — prints usage info and exits. when you're lost, she's there. 🫶
  • -v, --verbose — verbose mode is off by default, and this turns it ON. more talking, more info.
  • -p {off | on | lo[w] | hi[gh] | <value>} — clock profiling control, babes. off disables it, on enables it with a default sampling granularity, or you can enable it implicitly by setting the sampling granularity yourself: lo[w], hi[gh], or a specific value in ms. default is clock profiling enabled (-p on). ⏰
  • -h <ctr_def>[,<ctr_def>] — enables hardware event counter profiling and picks one or more counter(s) for you. wanna see what counters this system even supports? run the -h option with no other arguments. no cap. 🔥
  • -o <exp_name> — names the experiment directory. the name has to end with .er and it may contain an absolute path (like /tmp/experiment.er). and bestie, note this: an existing experiment with the same name will not be overwritten. she's polite like that. 🙈
  • -O <exp_name> — same as -o, but here's the difference: unlike -o, this one silently overwrites an existing experiment directory with the same name. so like. be aware. 💀
  • -C <comment_string> — adds up to 10 comment strings to the experiment. these comments show up in the notes section of the header and you can pull them back with the gprofng display text command using the -header option. cute lil sticky notes. 🎀
  • -j {on | off | <path>} — controls Java profiling when the target is a JVM machine. allowed values:
    • on — records profiling data for the JVM machine, and recognizes methods compiled by the Java HotSpot virtual machine. also records Java call stacks.
    • off — do not record Java profiling data. profiling data for native call stacks is still recorded though, she's not gonna leave you empty-handed.
    • <path> — records profiling data for the JVM, and uses the JVM as installed in <path>.

the default is -j on.

  • -J <jvm-option(s)> — specifies one or more additional options to pass to the JVM being used. if it's more than one option, the jvm-option(s) list must be enclosed in quotation marks. items in the list need to be separated by spaces or tabs, and each item gets passed as its own separate option to the JVM. also note: this option implies -j on. 📢
  • -t <duration>[m|s] — collects data for the specified duration. the duration can be a single number, optionally followed by m for minutes or s for seconds — and s is the default.

the duration can also be two numbers separated by a minus (-) sign. one number given? data's collected from the start of the run until that given time. two numbers? data's collected from the first time to the second. if the second time is zero, data's collected until the end of the run. and if two non-zero numbers are given, the first must be less than the second. 👑

  • -n — dry run, bestie. several run-time settings get displayed, but the target is not executed and no performance data is collected. it's giving window shopping. 🛍️
  • -F {off|on|=regex} — controls whether descendant processes should have their data recorded. off/on to disable/enable. use =regex to record data on those processes whose executable name matches the regular expression. only the basename of the executable is used, not the full path. if you're using spaces or characters the shell would interpret, wrap that regex in single quotes. the default is -F on.
  • -a {off|on|ldobjects|src|usedldobjects|usedsrc} — specifies archiving of binaries and other files. besides disabling this feature (off) or enabling archiving of all loadobjects and sources (on), the other options support a more refined selection.

all of these options enable archiving, but the keyword controls exactly what gets selected: all load objects (ldobjects), all source files (src), the loadobjects asscoiated with a program counter (usedldobjects), or the source files associated with a program counter (usedsrc). the default is -a ldobjects. 📦

  • -S {off|on|<seconds>} — disables (off) or enables (on) periodic sampling of process-wide resource utilization. by default, sampling happens every second. use the <seconds> option to change that. the default is -S on. ⏱️
  • -y <signal>[,r] — controls recording of data with the signal named <signal>, aka the pause-resume signal. whenever that signal gets delivered to the process, she switches between paused (no data recorded) and resumed (data recorded) states.

by default, data collection begins in the paused state. if the optional r is given, data collection begins in the resumed state and data collection begins immediately.

SIGUSR1 or SIGUSR2 are recommended for this, but honestly any signal that isn't used by the target can be used. 🚦

  • -l <signal> — specify a signal that will trigger a sample of process-wide resource utilization. when the named <signal> is delivered to the process, a sample gets recorded.

the signal can be specified using the full name, without the initial letters "SIG", or the signal number. note that the kill command can be used to deliver a signal.

if both the -l and -y options are used, the signals must be different. don't be messy. 💅

  • -s <option>[,<API>] — enables synchronization wait tracing, where <option> defines the specifics of the tracing (on, off, <threshold>, or all). the API is selected through the setting for <API>: n selects native/Pthreads, j selects Java, and nj selects both. the default is -s off.
  • -H {off|on} — disables (off) or enables (on) heap tracing. the default is -H off. 🧺
  • -i {off|on} — disables (off) or enables (on) I/O tracing. the default is -i off. 📥

🧚 NOTES 🧚

any executable in the ELF (Executable and Linkable Format) object format can be used for profiling with gprofng. if debug information is available, gprofng can provide more details, but bestie — that is not a requirement. you can absolutely show up without it. 💜

🌈 SEE ALSO 🌈

the user guide for gprofng is maintained as a Texinfo manual. if the info and gprofng programs are correctly installed, the command info gprofng should give access to this document. 📖

Copyright (c) 2022-2026 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

k that's the whole thing, no skipped parts, nothing left out. this page is from binutils-2.47 and it's dated 2026-09-10 — so yeah, she's current, she's iconic, and she's ready to collect. go get your data bestie 💖✨🦋

📦 where this page comes from