1@c ---------------------------------------------------------------------------- 2@c This is the Texinfo source file for the gp-collect-app man page. 3@c 4@c Author: Ruud van der Pas 5@c ---------------------------------------------------------------------------- 6@ifset man 7\input texinfo @c -*-texinfo-*- 8@setfilename gp-collect-app 9@settitle Collect performance data for the target application 10@include gp-macros.texi 11@end ifset 12 13@c ---------------------------------------------------------------------------- 14@c This is from the man-pages(7) man page 15@c 16@c "The list below shows conventional or suggested sections. Most manual pages 17@c should include at least the highlighted sections. Arrange a new manual 18@c page so that sections are placed in the order shown in the list." 19@c 20@c NAME 21@c SYNOPSIS 22@c CONFIGURATION [Normally only in Section 4] 23@c DESCRIPTION 24@c OPTIONS [Normally only in Sections 1, 8] 25@c EXIT STATUS [Normally only in Sections 1, 8] 26@c RETURN VALUE [Normally only in Sections 2, 3] 27@c ERRORS [Typically only in Sections 2, 3] 28@c ENVIRONMENT 29@c FILES 30@c VERSIONS [Normally only in Sections 2, 3] 31@c ATTRIBUTES [Normally only in Sections 2, 3] 32@c CONFORMING TO 33@c NOTES 34@c BUGS 35@c EXAMPLES 36@c AUTHORS [Discouraged] 37@c REPORTING BUGS [Not used in man-pages] 38@c COPYRIGHT [Not used in man-pages] 39@c SEE ALSO 40@c 41@c This is what the texi2pod.pl tool recognizes: 42@c 43@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES 44@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) { 45@c 46@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which 47@c makes sense and adhered to for the other formats. 48@c ---------------------------------------------------------------------------- 49 50@c ---------------------------------------------------------------------------- 51@c NAME section 52@c ---------------------------------------------------------------------------- 53 54@ManPageStart{NAME} 55@c man begin NAME 56 57gp-collect-app - Collect performance data for the target program 58 59@c man end 60@ManPageEnd{} 61 62@c ---------------------------------------------------------------------------- 63@c SYNOPSIS section 64@c ---------------------------------------------------------------------------- 65 66@ManPageStart{SYNOPSIS} 67@c man begin SYNOPSIS 68 69@command{gprofng collect app} [@var{option(s)}] @var{target} 70[@var{target-option(s)}] 71 72@c man end 73@ManPageEnd{} 74 75@c ---------------------------------------------------------------------------- 76@c DESCRIPTION section 77@c ---------------------------------------------------------------------------- 78 79@ManPageStart{DESCRIPTION} 80@c man begin DESCRIPTION 81 82Collect performance data on the target program. In addition to Program Counter 83(PC) sampling, hardware event counters and various tracing options are 84supported. 85 86For example, this command collects performance data for an executable called 87@samp{a.out} and stores the data collected in an experiment directory with 88the name @samp{example.er}. 89 90@smallexample 91$ gprofng collect app -o example.er ./a.out 92@end smallexample 93 94@c man end 95@ManPageEnd{} 96 97@c ---------------------------------------------------------------------------- 98@c OPTIONS section 99@c ---------------------------------------------------------------------------- 100 101@ManPageStart{OPTIONS} 102@c man begin OPTIONS 103 104@table @gcctabopt 105 106@item --version 107@ifclear man 108@IndexSubentry{Options, @code{--version}} 109@end ifclear 110 111Print the version number and exit. 112 113@item --help 114@ifclear man 115@IndexSubentry{Options, @code{--help}} 116@end ifclear 117 118Print usage information and exit. 119 120@item -v, --verbose 121@ifclear man 122@IndexSubentry{Options, @code{-v}} 123@IndexSubentry{Options, @code{--verbose}} 124@end ifclear 125 126By default, verbose mode is disabled. This option enables it. 127 128@item -p @{off | on | lo[w] | hi[gh] | @var{<value>}@} 129@ifclear man 130@IndexSubentry{Options, @code{-p}} 131@end ifclear 132 133Disable (@samp{off}) or enable (@samp{on}) clock profiling using a default 134sampling granularity, or enable clock profiling implicitly by setting the 135sampling granularity (@samp{lo[w]}, @samp{hi[gh]}, or a specific value in 136ms). By default, clock profiling is enabled (@samp{-p on}). 137 138@item -h @var{<ctr_def>[,<ctr_def>]} 139@ifclear man 140@IndexSubentry{Options, @code{-h}} 141@end ifclear 142Enable hardware event counter profiling and select one or more counter(s). 143To see the supported counters on this system, use the @samp{-h} option 144without other arguments. 145 146@item -o @var{<exp_name>} 147@ifclear man 148@IndexSubentry{Options, @code{-o}} 149@end ifclear 150 151Specify the name for the experiment directory. The name has to end with 152@samp{.er} and may contain an absolute path (e.g. @file{/tmp/experiment.er}). 153An existing experiment with the same name will not be overwritten. 154 155@item -O @var{<exp_name>} 156@ifclear man 157@IndexSubentry{Options, @code{-O}} 158@end ifclear 159 160This is the same as the @samp{-o} option, but unlike this option, silently 161overwrites an existing experiment directory with the same name. 162 163@item -C @var{<comment_string>} 164@ifclear man 165@IndexSubentry{Options, @code{-C}} 166@end ifclear 167 168Add up to 10 comment strings to the experiment. These comments appear in the 169notes section of the header and can be retrieved with the 170@command{gprofng display text} command using the @samp{-header} option. 171@ifclear man 172@IndexSubentry{Options, @code{-header}} 173@IndexSubentry{Commands, @code{-header}} 174@end ifclear 175 176@item -j @{on | off | @var{<path>}@} 177@ifclear man 178@IndexSubentry{Options, @code{-j}} 179@end ifclear 180 181Controls Java profiling when the target is a JVM machine. The allowed values 182for this option are: 183 184@table @gcctabopt 185 186@item on 187Record profiling data for the JVM machine, and recognize methods compiled by 188the Java HotSpot virtual machine. Also record Java call stacks. 189 190@item off 191Do not record Java profiling data. Profiling data for native call stacks is 192still recorded. 193 194@item @var{<path>} 195Records profiling data for the JVM, and use the JVM as installed in 196@var{<path>}. 197 198@end table 199 200The default is @samp{-j on}. 201 202@item -J @var{<jvm-option(s)>} 203@ifclear man 204@IndexSubentry{Options, @code{-J}} 205@end ifclear 206 207Specifies one or more additional options to be passed to the JVM used. The 208@var{jvm-option(s)} list must be enclosed in quotation marks if it contains 209more than one option. The items in the list need to be separated by spaces 210or tabs. 211Each item is passed as a separate option to the JVM. Note that this option 212implies @samp{-j on}. 213 214@item -t @var{<duration>}[m|s] 215@ifclear man 216@IndexSubentry{Options, @code{-t}} 217@end ifclear 218 219Collects data for the specified duration. The duration can be a single number, 220optionally followed by either @samp{m} to specify minutes, or @samp{s} to 221specify seconds, which is the default. 222 223The duration can also consists of two numbers separated by a minus (@minus{}) 224sign. If a single number is given, data is collected from the start of the run 225until the given time. 226If two numbers are given, data is collected from the first time to the second. 227In case the second time is zero, data is collected until the end of the run. 228If two non-zero numbers are given, the first must be less than the second. 229 230@item -n 231@ifclear man 232@IndexSubentry{Options, @code{-n}} 233@end ifclear 234 235This is used for a dry run. Several run-time settings are displayed, but the 236target is not executed and no performance data is collected. 237 238@item -F @{off|on|=@var{regex}@} 239@ifclear man 240@IndexSubentry{Options, @code{-F}} 241@end ifclear 242 243Control whether descendant processes should have their data recorded. 244To disable/enable this feature, use @samp{off}/@samp{on}. Use 245@samp{=}@var{regex} to record data on those processes whose executable name 246matches the regular expression. Only the basename of the executable is used, 247not the full path. If spaces or characters interpreted by the shell are used, 248enclose the @var{regex} in single quotes. The default is @samp{-F on}. 249 250@item -a @{off|on|ldobjects|src|usedldobjects|usedsrc@} 251@ifclear man 252@IndexSubentry{Options, @code{-a}} 253@end ifclear 254 255Specify archiving of binaries and other files. In addition to disable this 256feature (@samp{off}), or enable archiving off all loadobjects and sources 257(@samp{on}), the other options support a more refined selection. 258 259All of these options enable archiving, but the keyword controls what exactly 260is selected: all load objects (ldobjects), all source files (src), the 261loadobjects asscoiated with a program counter (usedldobjects), or the source 262files associated with a program counter (usedsrc). 263The default is @samp{-a ldobjects}. 264 265@item -S @{off|on|@var{<seconds>}@} 266@ifclear man 267@IndexSubentry{Options, @code{-S}} 268@end ifclear 269 270Disable (off), or enable (on) periodic sampling of process-wide 271resource utilization. By default, sampling occurs every second. Use the 272@var{<seconds>} option to change this. The default is @samp{-S on}. 273 274@item -y @var{<signal>}[,r] 275@ifclear man 276@IndexSubentry{Options, @code{-y}} 277@end ifclear 278 279Controls recording of data with the signal named @var{<signal>}, referred to 280as the pause-resume signal. Whenever the given signal is delivered to the 281process, switch between paused (no data is recorded) and resumed (data is 282recorded) states. 283 284By default, data collection begins in the paused state. If the optional 285@samp{r} is given, data collection begins in the resumed state and data 286collection begins immediately. 287 288SIGUSR1 or SIGUSR2 are recommended for this use, but any signal that is 289not used by the target can be used. 290 291@item -l @var{<signal>} 292@ifclear man 293@IndexSubentry{Options, @code{-l}} 294@end ifclear 295 296Specify a signal that will trigger a sample of process-wide resource 297utilization. When the named @var{<signal>} is delivered to the process, 298a sample is recorded. 299 300The signal can be specified using the full name, without the initial 301letters @code{SIG}, or the signal number. Note that the @command{kill} 302command can be used to deliver a signal. 303 304If both the @samp{-l} and @samp{-y} options are used, the signal must be 305different. 306 307@item -s @var{<option>}[,@var{<API>}] 308@ifclear man 309@IndexSubentry{Options, @code{-s}} 310@end ifclear 311 312Enable synchronization wait tracing, where @var{<option>} is used to define the 313specifics of the tracing (on, off, @var{<threshold>}, or all). The API is 314selected through the setting for @var{<API>}: @samp{n} selects native/Pthreads, 315@samp{j} selects Java, and @samp{nj} selects both. The default is 316@samp{-s off}. 317 318@item -H @{off|on@} 319@ifclear man 320@IndexSubentry{Options, @code{-H}} 321@end ifclear 322 323Disable (off), or enable (on) heap tracing. The default is @samp{-H off}. 324 325@item -i @{off|on@} 326@ifclear man 327@IndexSubentry{Options, @code{-i}} 328@end ifclear 329 330Disable (off), or enable (on) I/O tracing. The default is @samp{-i off}. 331 332@end table 333 334@c man end 335@ManPageEnd{} 336 337@c ---------------------------------------------------------------------------- 338@c NOTES section 339@c ---------------------------------------------------------------------------- 340 341@ManPageStart{NOTES} 342@c man begin NOTES 343 344Any executable in the ELF (Executable and Linkable Format) object format can 345be used for profiling with gprofng. If debug information is available, 346gprofng can provide more details, but this is not a requirement. 347 348@c man end 349@ManPageEnd{} 350 351@c ---------------------------------------------------------------------------- 352@c SEEALSO section 353@c ---------------------------------------------------------------------------- 354 355@ManPageStart{SEE ALSO} 356@c man begin SEEALSO 357 358gprofng(1), 359gp-archive(1), 360gp-display-gui(1), 361gp-display-html(1), 362gp-display-src(1), 363gp-display-text(1) 364 365@iftex 366@vspace{1} 367@end iftex 368 369The user guide for gprofng is maintained as a Texinfo manual. If the 370@command{info} and @command{gprofng} programs are correctly installed, the 371command @command{info gprofng} should give access to this document. 372 373@c man end 374@ManPageEnd{} 375 376@c ---------------------------------------------------------------------------- 377@c COPYRIGHT section 378@c ---------------------------------------------------------------------------- 379 380@ManPageStart{COPYRIGHT} 381@c man begin COPYRIGHT 382 383Copyright @copyright{} 2022-2024 Free Software Foundation, Inc. 384 385Permission is granted to copy, distribute and/or modify this document 386under the terms of the GNU Free Documentation License, Version 1.3 387or any later version published by the Free Software Foundation; 388with no Invariant Sections, with no Front-Cover Texts, and with no 389Back-Cover Texts. A copy of the license is included in the 390section entitled ``GNU Free Documentation License''. 391 392@c man end 393@ManPageEnd{} 394 395@c ---------------------------------------------------------------------------- 396@c If this text is used for a man page, exit. Otherwise we need to continue. 397@c ---------------------------------------------------------------------------- 398 399@ifset man 400@bye 401@end ifset 402