diff options
Diffstat (limited to 'upstream/debian-unstable/man1/gp-collect-app.1')
| -rw-r--r-- | upstream/debian-unstable/man1/gp-collect-app.1 | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/gp-collect-app.1 b/upstream/debian-unstable/man1/gp-collect-app.1 new file mode 100644 index 00000000..e0569029 --- /dev/null +++ b/upstream/debian-unstable/man1/gp-collect-app.1 @@ -0,0 +1,252 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" 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'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "GP-COLLECT-APP.1 1" +.TH GP-COLLECT-APP.1 1 2024-02-21 binutils-2.42 "User Commands" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +gp\-collect\-app \- Collect performance data for the target application +.SH SYNOPSIS +.IX Header "SYNOPSIS" +\&\fBgprofng collect app\fR [\fIoption(s)\fR] \fItarget\fR +[\fItarget\-option(s)\fR] +.SH DESCRIPTION +.IX 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. +.PP +For example, this command collects performance data for an executable called +\&\fBa.out\fR and stores the data collected in an experiment directory with +the name \fBexample.er\fR. +.PP +.Vb 1 +\& $ gprofng collect app \-o example.er ./a.out +.Ve +.SH OPTIONS +.IX Header "OPTIONS" +.IP \fB\-\-version\fR 4 +.IX Item "--version" +Print the version number and exit. +.IP \fB\-\-help\fR 4 +.IX Item "--help" +Print usage information and exit. +.IP "\fB\-v, \-\-verbose\fR" 4 +.IX Item "-v, --verbose" +By default, verbose mode is disabled. This option enables it. +.IP "\fB\-p {off | on | lo[w] | hi[gh] |\fR \fI<value>\fR\fB}\fR" 4 +.IX Item "-p {off | on | lo[w] | hi[gh] | <value>}" +Disable (\fBoff\fR) or enable (\fBon\fR) clock profiling using a default +sampling granularity, or enable clock profiling implicitly by setting the +sampling granularity (\fBlo[w]\fR, \fBhi[gh]\fR, or a specific value in +ms). By default, clock profiling is enabled (\fB\-p on\fR). +.IP "\fB\-h\fR \fI<ctr_def>[,<ctr_def>]\fR" 4 +.IX 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 \fB\-h\fR option +without other arguments. +.IP "\fB\-o\fR \fI<exp_name>\fR" 4 +.IX Item "-o <exp_name>" +Specify the name for the experiment directory. The name has to end with +\&\fB.er\fR and may contain an absolute path (e.g. \fI/tmp/experiment.er\fR). +An existing experiment with the same name will not be overwritten. +.IP "\fB\-O\fR \fI<exp_name>\fR" 4 +.IX Item "-O <exp_name>" +This is the same as the \fB\-o\fR option, but unlike this option, silently +overwrites an existing experiment directory with the same name. +.IP "\fB\-C\fR \fI<comment_string>\fR" 4 +.IX 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\fR command using the \fB\-header\fR option. +.IP "\fB\-j {on | off |\fR \fI<path>\fR\fB}\fR" 4 +.IX Item "-j {on | off | <path>}" +Controls Java profiling when the target is a JVM machine. The allowed values +for this option are: +.RS 4 +.IP \fBon\fR 4 +.IX Item "on" +Record profiling data for the JVM machine, and recognize methods compiled by +the Java HotSpot virtual machine. Also record Java call stacks. +.IP \fBoff\fR 4 +.IX Item "off" +Do not record Java profiling data. Profiling data for native call stacks is +still recorded. +.IP \fI<path>\fR 4 +.IX Item "<path>" +Records profiling data for the JVM, and use the JVM as installed in +\&\fI<path>\fR. +.RE +.RS 4 +.Sp +The default is \fB\-j on\fR. +.RE +.IP "\fB\-J\fR \fI<jvm\-option(s)>\fR" 4 +.IX Item "-J <jvm-option(s)>" +Specifies one or more additional options to be passed to the JVM used. The +\&\fIjvm\-option(s)\fR 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 \fB\-j on\fR. +.IP "\fB\-t\fR \fI<duration>\fR\fB[m|s]\fR" 4 +.IX Item "-t <duration>[m|s]" +Collects data for the specified duration. The duration can be a single number, +optionally followed by either \fBm\fR to specify minutes, or \fBs\fR 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. +.IP \fB\-n\fR 4 +.IX 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. +.IP "\fB\-F {off|on|=\fR\fIregex\fR\fB}\fR" 4 +.IX Item "-F {off|on|=regex}" +Control whether descendant processes should have their data recorded. +To disable/enable this feature, use \fBoff\fR/\fBon\fR. Use +\&\fB=\fR\fIregex\fR 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 \fIregex\fR in single quotes. The default is \fB\-F on\fR. +.IP "\fB\-a {off|on|ldobjects|src|usedldobjects|usedsrc}\fR" 4 +.IX Item "-a {off|on|ldobjects|src|usedldobjects|usedsrc}" +Specify archiving of binaries and other files. In addition to disable this +feature (\fBoff\fR), or enable archiving off all loadobjects and sources +(\fBon\fR), 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 \fB\-a ldobjects\fR. +.IP "\fB\-S {off|on|\fR\fI<seconds>\fR\fB}\fR" 4 +.IX 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>\fR option to change this. The default is \fB\-S on\fR. +.IP "\fB\-y\fR \fI<signal>\fR\fB[,r]\fR" 4 +.IX Item "-y <signal>[,r]" +Controls recording of data with the signal named \fI<signal>\fR, 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\fR 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. +.IP "\fB\-l\fR \fI<signal>\fR" 4 +.IX Item "-l <signal>" +Specify a signal that will trigger a sample of process-wide resource +utilization. When the named \fI<signal>\fR is delivered to the process, +a sample is recorded. +.Sp +The signal can be specified using the full name, without the initial +letters \f(CW\*(C`SIG\*(C'\fR, or the signal number. Note that the \fBkill\fR +command can be used to deliver a signal. +.Sp +If both the \fB\-l\fR and \fB\-y\fR options are used, the signal must be +different. +.IP "\fB\-s\fR \fI<option>\fR\fB[,\fR\fI<API>\fR\fB]\fR" 4 +.IX Item "-s <option>[,<API>]" +Enable synchronization wait tracing, where \fI<option>\fR is used to define the +specifics of the tracing (on, off, \fI<threshold>\fR, or all). The API is +selected through the setting for \fI<API>\fR: \fBn\fR selects native/Pthreads, +\&\fBj\fR selects Java, and \fBnj\fR selects both. The default is +\&\fB\-s off\fR. +.IP "\fB\-H {off|on}\fR" 4 +.IX Item "-H {off|on}" +Disable (off), or enable (on) heap tracing. The default is \fB\-H off\fR. +.IP "\fB\-i {off|on}\fR" 4 +.IX Item "-i {off|on}" +Disable (off), or enable (on) I/O tracing. The default is \fB\-i off\fR. +.SH NOTES +.IX 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. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBgprofng\fR\|(1), +\&\fBgp\-archive\fR\|(1), +\&\fBgp\-display\-gui\fR\|(1), +\&\fBgp\-display\-html\fR\|(1), +\&\fBgp\-display\-src\fR\|(1), +\&\fBgp\-display\-text\fR\|(1) +.PP +The user guide for gprofng is maintained as a Texinfo manual. If the +\&\fBinfo\fR and \fBgprofng\fR programs are correctly installed, the +command \fBinfo gprofng\fR should give access to this document. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 2022\-2024 Free Software Foundation, Inc. +.PP +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". |