GP-COLLECT-APP.1(1)

📦
version 2.42 · 6 versions
, in ubuntu noble

💖 GP-COLLECT-APP 💖

okay bestie, welcome to the manual page for gp-collect-app — that's the User Commands section, page 1, iykyk. this is the lil glow-up guide to collecting performance data on a target app with gprofng. let's get into it fr fr ✨

🌸 NAME 🌸

gp-collect-app — collect performance data for the target application. yes queen, that's the whole job.

🦋 SYNOPSIS 🦋

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

✨ DESCRIPTION ✨

so basically: you collect performance data on the target program. and it's not just one vibe — Program Counter (PC) sampling is there, hardware event counters are there, and a whole menu of tracing options too. it's giving full-coverage bestie 💅

for example — this command collects performance data for an executable called a.out and stores the data collected in an experiment directory with the name example.er:

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

ate. no crumbs. 🍓

🎀 OPTIONS 🎀

  • --version — prints the version number and dips. that's it, that's the whole thing.
  • --help — prints usage information and exits. your little map 🗺️
  • -v, --verbose — verbose mode is off by default, and this option turns it on. (very "turn the volume up" energy 🔊)
  • -p {off | on | lo[w] | hi[gh] | <value>} — controls clock profiling. off disables it, on enables it with a default sampling granularity, and lo[w], hi[gh], or a specific <value> in ms enables clock profiling implicitly by setting the sampling granularity. by default, clock profiling is enabled — that's -p on. ⏰
  • -h <ctr_def>[,<ctr_def>] — enables hardware event counter profiling and picks one or more counter(s). want to see which counters your system supports? run -h with no other arguments and it'll spill the tea. 🔥
  • -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). heads up: an existing experiment with the same name will not be overwritten. no sneaky overwrites here 🙈
  • -O <exp_name> — same as -o, except it silently overwrites an existing experiment directory with the same name. yes literally silently. chaotic but intentional 💀
  • -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 get them back with the gprofng display text command using the -header option. little diary entries for your data 📝
  • -j {on | off | <path>} — controls Java profiling when the target is a JVM machine. the allowed values are:
    • on — record profiling data for the JVM machine, and recognize 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, tho.
    • <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 be passed to the JVM used. the jvm-option(s) list must be enclosed in quotation marks if it contains more than one option, and the items in the list need to be separated by spaces or tabs. each item is passed as a 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 either m for minutes or s for seconds — and seconds is the default.

the duration can also consist of two numbers separated by a minus (-) sign. if a single number is given, data is collected from the start of the run until the given time. if two numbers are given, data is collected from the first time to the second. in case the second time is zero, data is collected until the end of the run. and if two non-zero numbers are given, the first must be less than the second — rules are rules bestie ⏳

  • -n — dry run time! several run-time settings are displayed, but the target is not executed and no performance data is collected. window shopping only 🛍️
  • -F {off|on|=regex} — controls whether descendant processes should have their data recorded. use off/on to disable/enable this feature. 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 spaces or characters interpreted by the shell are used, enclose the 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 the 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 what exactly gets selected: all load objects (ldobjects), all source files (src), the loadobjects associated 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 the given signal is delivered to the process, it switches between paused (no data is recorded) and resumed (data is 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 use, but any signal that isn't used by the target can be used. ⏯️

  • -l <signal> — specifies a signal that will trigger a sample of process-wide resource utilization. when the named <signal> is delivered to the process, a sample is 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 signal must be different. no double-dipping 🚫

  • -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 that is not a requirement. so like, debug info is the cute accessory, not the outfit 👑

🌟 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-2024 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".

and that's a wrap, bestie 💖 this page came to you courtesy of binutils-2.42, dated 2025-12-03. go collect some data, you absolute icon 🎀✨🦋

📦 where this page comes from