GPROFNG-COLLECT-APP(1) User Commands GPROFNG-COLLECT-APP(1)
NAME
gprofng-collect-app - Collect performance data for the target application
SYNOPSIS
gprofng collect app [option(s)] target [target-option(s)]
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 a.out and stores the data collected in
an experiment directory with the name example.er.
$ gprofng collect app -o example.er ./a.out
OPTIONS
--version
Print the version number and exit.
--help
Print usage information and exit.
-v, --verbose
By default, verbose mode is disabled. This option enables it.
-p {off | on | lo[w] | hi[gh] | }
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 [,]
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
Specify the name for the experiment directory. The name has to end with .er and may contain an absolute path
(e.g. /tmp/experiment.er). An existing experiment with the same name will not be overwritten.
-O
This is the same as the -o option, but unlike this option, silently overwrites an existing experiment directory
with the same name.
-C
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 gprofng display text command using the -header option.
-j {on | off | }
Controls Java profiling when the target is a JVM machine. The allowed values for this option are:
on Record profiling data for the JVM machine, and recognize methods compiled by the Java HotSpot virtual
machine. Also record Java call stacks.
off Do not record Java profiling data. Profiling data for native call stacks is still recorded.
Records profiling data for the JVM, and use the JVM as installed in .
The default is -j on.
-J
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. 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 [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.
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 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}
Control whether descendant processes should have their data recorded. To disable/enable this feature, use
off/on. 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}
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.
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|}
Disable (off), or enable (on) periodic sampling of process-wide resource utilization. By default, sampling
occurs every second. Use the option to change this. The default is -S on.
-y [,r]
Controls recording of data with the signal named , 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.
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 is not used by the target can be used.
-l
Specify a signal that will trigger a sample of process-wide resource utilization. When the named 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.
-s