-*- mode: troff; coding: utf-8 -*- Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) Standard preamble: ========================================================================..
..
..
\*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.. ds C` ""
. ds C' ""
'br\}
. ds C`
. ds C'
'br\}
Escape single quotes in literal strings from groff's Unicode transform. If the F register is >0, we'll generate index entries on stderr for titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index entries marked with X<> in POD. Of course, you'll have to process the output yourself in some meaningful fashion. Avoid warning from groff about undefined register 'F'...
.nr rF 0
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
======================================================================== Title "GP-COLLECT-APP.1 1" GP-COLLECT-APP.1 1 2024-01-29 binutils-2.42 "User Commands"
For nroff, turn off justification. Always turn off hyphenation; it makes way too many mistakes in technical documents. NAME
gp-collect-app - Collect performance data for the target application
SYNOPSIS
Header "SYNOPSIS" \fBgprofng collect app [
option(s)]
target
[
target-option(s)]
DESCRIPTION
Header "DESCRIPTION" Collect performance data on the target program. In addition to Program Counter
(PC) sampling, hardware event counters and various tracing options are
supported.
For example, this command collects performance data for an executable called
\fBa.out and stores the data collected in an experiment directory with
the name example.er.
.Vb 1
$ gprofng collect app -o example.er ./a.out
.Ve
OPTIONS
Header "OPTIONS" --version 4
Item "--version" Print the version number and exit.
--help 4
Item "--help" Print usage information and exit.
"-v, --verbose" 4
Item "-v, --verbose" By default, verbose mode is disabled. This option enables it.
"-p {off | on | lo[w] | hi[gh] | <value>}" 4
Item "-p {off | on | lo[w] | hi[gh] | <value>}" Disable (
off) or enable (
on) clock profiling using a default
sampling granularity, or enable clock profiling implicitly by setting the
sampling granularity (
lo[w],
hi[gh], or a specific value in
ms). By default, clock profiling is enabled (
-p on).
"-h <ctr_def>[,<ctr_def>]" 4
Item "-h <ctr_def>[,<ctr_def>]" Enable hardware event counter profiling and select one or more counter(s).
To see the supported counters on this system, use the
-h option
without other arguments.
"-o <exp_name>" 4
Item "-o <exp_name>" Specify the name for the experiment directory. The name has to end with
\fB.er and may contain an absolute path (e.g.
/tmp/experiment.er).
An existing experiment with the same name will not be overwritten.
"-O <exp_name>" 4
Item "-O <exp_name>" This is the same as the
-o option, but unlike this option, silently
overwrites an existing experiment directory with the same name.
"-C <comment_string>" 4
Item "-C <comment_string>" Add up to 10 comment strings to the experiment. These comments appear in the
notes section of the header and can be retrieved with the
\fBgprofng display text command using the
-header option.
"-j {on | off | <path>}" 4
Item "-j {on | off | <path>}" Controls Java profiling when the target is a JVM machine. The allowed values
for this option are:
on 4
Item "on" Record profiling data for the JVM machine, and recognize methods compiled by
the Java HotSpot virtual machine. Also record Java call stacks.
off 4
Item "off" Do not record Java profiling data. Profiling data for native call stacks is
still recorded.
<path> 4
Item "<path>" Records profiling data for the JVM, and use the JVM as installed in
\fI<path>.
.Sp
The default is -j on.
"-J <jvm-option(s)>" 4
Item "-J <jvm-option(s)>" Specifies one or more additional options to be passed to the JVM used. The
\fIjvm-option(s) list must be enclosed in quotation marks if it contains
more than one option. The items in the list need to be separated by spaces
or tabs.
Each item is passed as a separate option to the JVM. Note that this option
implies
-j on.
"-t <duration>[m|s]" 4
Item "-t <duration>[m|s]" Collects data for the specified duration. The duration can be a single number,
optionally followed by either
m to specify minutes, or
s to
specify seconds, which is the default.
.Sp
The duration can also consists 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.
If two non-zero numbers are given, the first must be less than the second.
-n 4
Item "-n" This is used for a dry run. Several run-time settings are displayed, but the
target is not executed and no performance data is collected.
"-F {off|on|=regex}" 4
Item "-F {off|on|=regex}" Control whether descendant processes should have their data recorded.
To
disable/
enable this feature, use
off/
on. Use
\fB=
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}" 4
Item "-a {off|on|ldobjects|src|usedldobjects|usedsrc}" Specify archiving of binaries and other files. In addition to disable this
feature (
off), or enable archiving off all loadobjects and sources
(
on), the other options support a more refined selection.
.Sp
All of these options enable archiving, but the keyword controls what exactly
is 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>}" 4
Item "-S {off|on|<seconds>}" Disable (off), or enable (on) periodic sampling of process-wide
resource utilization. By default, sampling occurs every second. Use the
\fI<seconds> option to change this. The default is
-S on.
"-y <signal>[,r]" 4
Item "-y <signal>[,r]" Controls recording of data with the signal named
<signal>, referred to
as the pause-resume signal. Whenever the given signal is delivered to the
process, switch between paused (no data is recorded) and resumed (data is
recorded) states.
.Sp
By default, data collection begins in the paused state. If the optional
\fBr is given, data collection begins in the resumed state and data
collection begins immediately.
.Sp
SIGUSR1 or SIGUSR2 are recommended for this use, but any signal that is
not used by the target can be used.
"-l <signal>" 4
Item "-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 is recorded.
.Sp
The signal can be specified using the full name, without the initial
letters
\*(C`SIG\*(C', or the signal number. Note that the
kill
command can be used to deliver a signal.
.Sp
If both the
-l and
-y options are used, the signal must be
different.
"-s <option>[,<API>]" 4
Item "-s <option>[,<API>]" Enable synchronization wait tracing, where
<option> is used to define the
specifics of the tracing (on, off,
<threshold>, or all). The API is
selected through the setting for
<API>:
n selects
native/
Pthreads,
\fBj selects Java, and
nj selects both. The default is
\fB-s off.
"-H {off|on}" 4
Item "-H {off|on}" Disable (off), or enable (on) heap tracing. The default is
-H off.
"-i {off|on}" 4
Item "-i {off|on}" Disable (off), or enable (on) I/O tracing. The default is
-i off.
NOTES
Header "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 this is not a requirement.
"SEE ALSO"
Header "SEE ALSO" \fBgprofng\|(1),
\fBgp-archive\|(1),
\fBgp-display-gui\|(1),
\fBgp-display-html\|(1),
\fBgp-display-src\|(1),
\fBgp-display-text\|(1)
The user guide for gprofng is maintained as a Texinfo manual. If the
\fBinfo and gprofng programs are correctly installed, the
command info gprofng should give access to this document.
COPYRIGHT
Header "COPYRIGHT" 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".