| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" |
| 56 |
.\" Required to disable full justification in groff 1.23.0. |
| 57 |
.if n .ds AD l |
| 58 |
.\" ======================================================================== |
| 59 |
.\" |
| 60 |
.IX Title "GPROFNG-COLLECT-APP 1" |
| 61 |
.TH GPROFNG-COLLECT-APP 1 2025-07-27 binutils-2.45 "User Commands" |
| 62 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 63 |
.\" way too many mistakes in technical documents. |
| 64 |
.if n .ad l |
| 65 |
.nh |
| 66 |
.SH NAME |
| 67 |
gprofng\-collect\-app \- Collect performance data for the target application |
| 68 |
.SH SYNOPSIS |
| 69 |
.IX Header "SYNOPSIS" |
| 70 |
\&\fBgprofng collect app\fR [\fIoption(s)\fR] \fItarget\fR |
| 71 |
[\fItarget\-option(s)\fR] |
| 72 |
.SH DESCRIPTION |
| 73 |
.IX Header "DESCRIPTION" |
| 74 |
Collect performance data on the target program. In addition to Program Counter |
| 75 |
(PC) sampling, hardware event counters and various tracing options are |
| 76 |
supported. |
| 77 |
.PP |
| 78 |
For example, this command collects performance data for an executable called |
| 79 |
\&\fBa.out\fR and stores the data collected in an experiment directory with |
| 80 |
the name \fBexample.er\fR. |
| 81 |
.PP |
| 82 |
.Vb 1 |
| 83 |
\& $ gprofng collect app \-o example.er ./a.out |
| 84 |
.Ve |
| 85 |
.SH OPTIONS |
| 86 |
.IX Header "OPTIONS" |
| 87 |
.IP \fB\-\-version\fR 4 |
| 88 |
.IX Item "--version" |
| 89 |
Print the version number and exit. |
| 90 |
.IP \fB\-\-help\fR 4 |
| 91 |
.IX Item "--help" |
| 92 |
Print usage information and exit. |
| 93 |
.IP "\fB\-v, \-\-verbose\fR" 4 |
| 94 |
.IX Item "-v, --verbose" |
| 95 |
By default, verbose mode is disabled. This option enables it. |
| 96 |
.IP "\fB\-p {off | on | lo[w] | hi[gh] |\fR \fI<value>\fR\fB}\fR" 4 |
| 97 |
.IX Item "-p {off | on | lo[w] | hi[gh] | <value>}" |
| 98 |
Disable (\fBoff\fR) or enable (\fBon\fR) clock profiling using a default |
| 99 |
sampling granularity, or enable clock profiling implicitly by setting the |
| 100 |
sampling granularity (\fBlo[w]\fR, \fBhi[gh]\fR, or a specific value in |
| 101 |
ms). By default, clock profiling is enabled (\fB\-p on\fR). |
| 102 |
.IP "\fB\-h\fR \fI<ctr_def>[,<ctr_def>]\fR" 4 |
| 103 |
.IX Item "-h <ctr_def>[,<ctr_def>]" |
| 104 |
Enable hardware event counter profiling and select one or more counter(s). |
| 105 |
To see the supported counters on this system, use the \fB\-h\fR option |
| 106 |
without other arguments. |
| 107 |
.IP "\fB\-o\fR \fI<exp_name>\fR" 4 |
| 108 |
.IX Item "-o <exp_name>" |
| 109 |
Specify the name for the experiment directory. The name has to end with |
| 110 |
\&\fB.er\fR and may contain an absolute path (e.g. \fI/tmp/experiment.er\fR). |
| 111 |
An existing experiment with the same name will not be overwritten. |
| 112 |
.IP "\fB\-O\fR \fI<exp_name>\fR" 4 |
| 113 |
.IX Item "-O <exp_name>" |
| 114 |
This is the same as the \fB\-o\fR option, but unlike this option, silently |
| 115 |
overwrites an existing experiment directory with the same name. |
| 116 |
.IP "\fB\-C\fR \fI<comment_string>\fR" 4 |
| 117 |
.IX Item "-C <comment_string>" |
| 118 |
Add up to 10 comment strings to the experiment. These comments appear in the |
| 119 |
notes section of the header and can be retrieved with the |
| 120 |
\&\fBgprofng display text\fR command using the \fB\-header\fR option. |
| 121 |
.IP "\fB\-j {on | off |\fR \fI<path>\fR\fB}\fR" 4 |
| 122 |
.IX Item "-j {on | off | <path>}" |
| 123 |
Controls Java profiling when the target is a JVM machine. The allowed values |
| 124 |
for this option are: |
| 125 |
.RS 4 |
| 126 |
.IP \fBon\fR 4 |
| 127 |
.IX Item "on" |
| 128 |
Record profiling data for the JVM machine, and recognize methods compiled by |
| 129 |
the Java HotSpot virtual machine. Also record Java call stacks. |
| 130 |
.IP \fBoff\fR 4 |
| 131 |
.IX Item "off" |
| 132 |
Do not record Java profiling data. Profiling data for native call stacks is |
| 133 |
still recorded. |
| 134 |
.IP \fI<path>\fR 4 |
| 135 |
.IX Item "<path>" |
| 136 |
Records profiling data for the JVM, and use the JVM as installed in |
| 137 |
\&\fI<path>\fR. |
| 138 |
.RE |
| 139 |
.RS 4 |
| 140 |
.Sp |
| 141 |
The default is \fB\-j on\fR. |
| 142 |
.RE |
| 143 |
.IP "\fB\-J\fR \fI<jvm\-option(s)>\fR" 4 |
| 144 |
.IX Item "-J <jvm-option(s)>" |
| 145 |
Specifies one or more additional options to be passed to the JVM used. The |
| 146 |
\&\fIjvm\-option(s)\fR list must be enclosed in quotation marks if it contains |
| 147 |
more than one option. The items in the list need to be separated by spaces |
| 148 |
or tabs. |
| 149 |
Each item is passed as a separate option to the JVM. Note that this option |
| 150 |
implies \fB\-j on\fR. |
| 151 |
.IP "\fB\-t\fR \fI<duration>\fR\fB[m|s]\fR" 4 |
| 152 |
.IX Item "-t <duration>[m|s]" |
| 153 |
Collects data for the specified duration. The duration can be a single number, |
| 154 |
optionally followed by either \fBm\fR to specify minutes, or \fBs\fR to |
| 155 |
specify seconds, which is the default. |
| 156 |
.Sp |
| 157 |
The duration can also consists of two numbers separated by a minus (\-) |
| 158 |
sign. If a single number is given, data is collected from the start of the run |
| 159 |
until the given time. |
| 160 |
If two numbers are given, data is collected from the first time to the second. |
| 161 |
In case the second time is zero, data is collected until the end of the run. |
| 162 |
If two non\-zero numbers are given, the first must be less than the second. |
| 163 |
.IP \fB\-n\fR 4 |
| 164 |
.IX Item "-n" |
| 165 |
This is used for a dry run. Several run\-time settings are displayed, but the |
| 166 |
target is not executed and no performance data is collected. |
| 167 |
.IP "\fB\-F {off|on|=\fR\fIregex\fR\fB}\fR" 4 |
| 168 |
.IX Item "-F {off|on|=regex}" |
| 169 |
Control whether descendant processes should have their data recorded. |
| 170 |
To disable/enable this feature, use \fBoff\fR/\fBon\fR. Use |
| 171 |
\&\fB=\fR\fIregex\fR to record data on those processes whose executable name |
| 172 |
matches the regular expression. Only the basename of the executable is used, |
| 173 |
not the full path. If spaces or characters interpreted by the shell are used, |
| 174 |
enclose the \fIregex\fR in single quotes. The default is \fB\-F on\fR. |
| 175 |
.IP "\fB\-a {off|on|ldobjects|src|usedldobjects|usedsrc}\fR" 4 |
| 176 |
.IX Item "-a {off|on|ldobjects|src|usedldobjects|usedsrc}" |
| 177 |
Specify archiving of binaries and other files. In addition to disable this |
| 178 |
feature (\fBoff\fR), or enable archiving off all loadobjects and sources |
| 179 |
(\fBon\fR), the other options support a more refined selection. |
| 180 |
.Sp |
| 181 |
All of these options enable archiving, but the keyword controls what exactly |
| 182 |
is selected: all load objects (ldobjects), all source files (src), the |
| 183 |
loadobjects asscoiated with a program counter (usedldobjects), or the source |
| 184 |
files associated with a program counter (usedsrc). |
| 185 |
The default is \fB\-a ldobjects\fR. |
| 186 |
.IP "\fB\-S {off|on|\fR\fI<seconds>\fR\fB}\fR" 4 |
| 187 |
.IX Item "-S {off|on|<seconds>}" |
| 188 |
Disable (off), or enable (on) periodic sampling of process\-wide |
| 189 |
resource utilization. By default, sampling occurs every second. Use the |
| 190 |
\&\fI<seconds>\fR option to change this. The default is \fB\-S on\fR. |
| 191 |
.IP "\fB\-y\fR \fI<signal>\fR\fB[,r]\fR" 4 |
| 192 |
.IX Item "-y <signal>[,r]" |
| 193 |
Controls recording of data with the signal named \fI<signal>\fR, referred to |
| 194 |
as the pause\-resume signal. Whenever the given signal is delivered to the |
| 195 |
process, switch between paused (no data is recorded) and resumed (data is |
| 196 |
recorded) states. |
| 197 |
.Sp |
| 198 |
By default, data collection begins in the paused state. If the optional |
| 199 |
\&\fBr\fR is given, data collection begins in the resumed state and data |
| 200 |
collection begins immediately. |
| 201 |
.Sp |
| 202 |
SIGUSR1 or SIGUSR2 are recommended for this use, but any signal that is |
| 203 |
not used by the target can be used. |
| 204 |
.IP "\fB\-l\fR \fI<signal>\fR" 4 |
| 205 |
.IX Item "-l <signal>" |
| 206 |
Specify a signal that will trigger a sample of process\-wide resource |
| 207 |
utilization. When the named \fI<signal>\fR is delivered to the process, |
| 208 |
a sample is recorded. |
| 209 |
.Sp |
| 210 |
The signal can be specified using the full name, without the initial |
| 211 |
letters \f(CW\*(C`SIG\*(C'\fR, or the signal number. Note that the \fBkill\fR |
| 212 |
command can be used to deliver a signal. |
| 213 |
.Sp |
| 214 |
If both the \fB\-l\fR and \fB\-y\fR options are used, the signal must be |
| 215 |
different. |
| 216 |
.IP "\fB\-s\fR \fI<option>\fR\fB[,\fR\fI<API>\fR\fB]\fR" 4 |
| 217 |
.IX Item "-s <option>[,<API>]" |
| 218 |
Enable synchronization wait tracing, where \fI<option>\fR is used to define the |
| 219 |
specifics of the tracing (on, off, \fI<threshold>\fR, or all). The API is |
| 220 |
selected through the setting for \fI<API>\fR: \fBn\fR selects native/Pthreads, |
| 221 |
\&\fBj\fR selects Java, and \fBnj\fR selects both. The default is |
| 222 |
\&\fB\-s off\fR. |
| 223 |
.IP "\fB\-H {off|on}\fR" 4 |
| 224 |
.IX Item "-H {off|on}" |
| 225 |
Disable (off), or enable (on) heap tracing. The default is \fB\-H off\fR. |
| 226 |
.IP "\fB\-i {off|on}\fR" 4 |
| 227 |
.IX Item "-i {off|on}" |
| 228 |
Disable (off), or enable (on) I/O tracing. The default is \fB\-i off\fR. |
| 229 |
.SH NOTES |
| 230 |
.IX Header "NOTES" |
| 231 |
Any executable in the ELF (Executable and Linkable Format) object format can |
| 232 |
be used for profiling with gprofng. If debug information is available, |
| 233 |
gprofng can provide more details, but this is not a requirement. |
| 234 |
.SH "SEE ALSO" |
| 235 |
.IX Header "SEE ALSO" |
| 236 |
\&\fBgprofng\fR\|(1), |
| 237 |
\&\fBgprofng\-archive\fR\|(1), |
| 238 |
\&\fBgprofng\-display\-html\fR\|(1), |
| 239 |
\&\fBgprofng\-display\-src\fR\|(1), |
| 240 |
\&\fBgprofng\-display\-text\fR\|(1) |
| 241 |
.PP |
| 242 |
The user guide for gprofng is maintained as a Texinfo manual. If the |
| 243 |
\&\fBinfo\fR and \fBgprofng\fR programs are correctly installed, the |
| 244 |
command \fBinfo gprofng\fR should give access to this document. |
| 245 |
.SH COPYRIGHT |
| 246 |
.IX Header "COPYRIGHT" |
| 247 |
Copyright (c) 2022\-2025 Free Software Foundation, Inc. |
| 248 |
.PP |
| 249 |
Permission is granted to copy, distribute and/or modify this document |
| 250 |
under the terms of the GNU Free Documentation License, Version 1.3 |
| 251 |
or any later version published by the Free Software Foundation; |
| 252 |
with no Invariant Sections, with no Front\-Cover Texts, and with no |
| 253 |
Back\-Cover Texts. A copy of the license is included in the |
| 254 |
section entitled "GNU Free Documentation License". |