Debian Codegraph @

upstream/opensuse-tumbleweed/man1/gprofng-collect-app.1

raw
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".