Skip to content

Commit c7f9875

Browse files
author
Alex Rønne Petersen
committed
[man] Rewrite the profiler-related man pages.
* Separate profiler module documentation into a new mono-profilers(1) page. * Add documentation for the aot and coverage profilers. * Rewrite the mprof-report(1) page to only talk about mprof-report itself. * Rewrite and update the profiler-related sections of mono(1). * Conform to man page formatting conventions.
1 parent cbe3098 commit c7f9875

File tree

5 files changed

+605
-670
lines changed

5 files changed

+605
-670
lines changed

‎CODEOWNERS

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535
/llvm @vargaz
3636

3737
/man @marek-safar @miguel
38-
/man/mprof-report.1 @alexrp
38+
/man/*prof* @alexrp
3939

4040
/mcs @marek-safar
4141

‎man/Makefile.am

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ man_MANS = \
5858
mono-configuration-crypto.1 \
5959
ccrewrite.1 \
6060
cccheck.1 \
61-
mono-symbolicate.1
61+
mono-symbolicate.1 \
62+
mono-profilers.1
6263

6364
EXTRA_DIST = $(man_MANS)

‎man/mono-profilers.1

Lines changed: 375 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,375 @@
1+
.TH mono-profilers 1
2+
.SH NAME
3+
mono\-profilers \- Mono's bundled profiler modules
4+
.SH SYNOPSIS
5+
\fBmono\ \-\-profile=log\fR[:\fIoption\fR,...] \fIprogram.exe\fR [\fIargs\fR]...
6+
.PP
7+
\fBmono\ \-\-profile=coverage\fR[:\fIoption\fR,...] \fIprogram.exe\fR [\fIargs\fR]...
8+
.PP
9+
\fBmono\ \-\-profile=aot\fR[:\fIoption\fR,...] \fIprogram.exe\fR [\fIargs\fR]...
10+
.SH DESCRIPTION
11+
Mono ships with a few profiler modules that enable most typical
12+
profiling scenarios. This page describes each of them in the sections
13+
below.
14+
.SH LOG PROFILER
15+
The log profiler is Mono's general-purpose performance profiler. It
16+
can collect a wide variety of data that can be analyzed by tools such
17+
as \fBmprof\-report\fR(1) or the Xamarin Profiler.
18+
.PP
19+
By default, the log profiler writes its output to \fIoutput.mlpd\fR.
20+
Refer to the \fImono/profiler/log.h\fR file in the Mono source tree
21+
for documentation on the log profiler's file format.
22+
.PP
23+
A default invocation of the log profiler gathers only basic data:
24+
Metadata load and unload events, thread start and stop events,
25+
performance counter samples, exception throws, etc. Most users will
26+
want to enable some of the heavier features such as GC allocation
27+
recording, statistical sampling, heap snapshotting (heapshots), or
28+
method entry and exit instrumentation. See the \fBOptions\fR
29+
sub-section.
30+
.PP
31+
Note that, in most realistic scenarios, the log profiler will record
32+
a vast amount of data. This can lead to very large log files. (The
33+
\fBzip\fR and \fBreport\fR options can help deal with this.)
34+
.SS Options
35+
The log profiler supports the following options:
36+
.TP
37+
\fBhelp\fR
38+
Print usage instructions.
39+
.TP
40+
\fBoutput\fR=[\fI+\fR|\fI#\fR|\fI|\fR]\fIfile\fR
41+
Write log data to \fIfile\fR. The optional modifiers are:
42+
.RS
43+
.ne 8
44+
.TP
45+
\fB+\fR
46+
The program PID is appended to the file name. For example,
47+
\fBoutput=+out.mlpd\fR outputs to \fIout.mlpd.1234\fR if the PID is
48+
\fB1234\fR.
49+
.TP
50+
\fB#\fR
51+
\fIfile\fR is parsed as a file descriptor number, which is opened
52+
with \fBfdopen\fR(3). This is mainly useful in embedding scenarios.
53+
.TP
54+
\fB|\fR
55+
\fIfile\fR is treated as a program name. It will be started with
56+
\fBpopen\fR(3) and the log data will be piped to its standard input.
57+
.RE
58+
.TP
59+
\fBreport\fR
60+
Generate a report directly instead of writing the log data to a file.
61+
If this option is used together with the \fBoutput\fR option, the
62+
report will be written to the specified file instead of the log data.
63+
.TP
64+
\fBzip\fR
65+
Compress the output file with \fBgzip\fR(1).
66+
.TP
67+
\fBport\fR=\fIport\fR
68+
Use \fIport\fR to listen for command server connections. See the
69+
\fBCommand server\fR sub-section.
70+
.TP
71+
\fBnodefaults\fR
72+
Disables pre Mono 5.6 compatibility. In particular, this disables
73+
exception events and performance counter sampling by default. It also
74+
makes it so that GC move events won't be enabled by default when
75+
heapshots are enabled. To use this option, it must be the first
76+
option given to the log profiler.
77+
.IP
78+
This option will be the default in a future version of the log
79+
profiler.
80+
.TP
81+
[\fBno\fR]\fIevent\fR
82+
Enable or disable gathering data for \fIevent\fR, which can be one
83+
of:
84+
.RS
85+
.TP
86+
\fBexception\fR
87+
Exception throw and clause (\fBcatch\fR, \fBfinally\fR, etc)
88+
evaluation events. Enabled by default unless \fBnodefaults\fR is
89+
used.
90+
.TP
91+
\fBmonitor\fR
92+
Monitor lock contention, acquisition, and release events.
93+
.TP
94+
\fBgc\fR
95+
GC start, progress, stop, and resize events.
96+
.TP
97+
\fBgcalloc\fR
98+
GC allocation events.
99+
.TP
100+
\fBgcmove\fR
101+
GC move events.
102+
.TP
103+
\fBgcroot\fR
104+
GC root report events. Generated on every collection if enabled,
105+
unless \fBnodefaults\fR is used, in which case, they're only
106+
generated on heapshots.
107+
.TP
108+
\fBgchandle\fR
109+
GC handle creation and deletion events.
110+
.TP
111+
\fBfinalization\fR
112+
Object finalization events.
113+
.TP
114+
\fBcounter\fR
115+
Performance counter sample events. Enabled by default unless
116+
\fBnodefaults\fR is used.
117+
.TP
118+
\fBjit\fR
119+
JIT code buffer events.
120+
.TP
121+
\fBalloc\fR
122+
Alias for \fBgc\fR, \fBgcalloc\fR, and \fBgcmove\fR.
123+
.TP
124+
\fBlegacy\fR
125+
Alias for \fBexception\fR, \fBmonitor\fR, \fBgc\fR, \fBgcmove\fR,
126+
\fBgcroot\fR, \fBgchandle\fR, \fBfinalization\fR, and \fBcounter\fR.
127+
.RE
128+
.TP
129+
\fBsample\fR[\fB\-real\fR][=\fIfreq\fR]
130+
Enable statistical sampling. The default is to sample at a frequency
131+
of 100 Hz, but \fIfreq\fR can be used to override this.
132+
.IP
133+
By default, sampling uses process time (i.e., the more work a process
134+
does, the more samples are collected). The \fB-real\fR variant uses
135+
wall clock time instead. Wall clock time is better for programs that
136+
are I/O-bound.
137+
.TP
138+
\fBmaxsamples\fR=\fInum\fR
139+
Limit the number of reusable sample events to \fInum\fR allocations.
140+
A value of zero means no limit. By default, the value of this setting
141+
is based on the number of CPU cores. Some tinkering with this setting
142+
may be necessary for programs with an unusually high amount of
143+
threads.
144+
.TP
145+
\fBcalls\fR
146+
Enable method entry and exit instrumentation. This is an alternative
147+
to statistical sampling when you need more precise information. Note
148+
that this mode is extremely heavy and can slow most programs to a
149+
crawl.
150+
.TP
151+
\fBcallspec\fR=\fIspec\fR
152+
Limit method entry and exit instrumentation to methods matching the
153+
specified call spec. This uses the same syntax as the \fB--trace\fR
154+
option for \fBmono\fR(1), so refer to that page for more information.
155+
.TP
156+
\fBcalldepth\fR=\fInum\fR
157+
Limit method entry and exit event collection to a call depth of
158+
\fInum\fR.
159+
.TP
160+
\fBmaxframes\fR=\fInum\fR
161+
Limit backtraces in various events (including statistical samples) to
162+
\fInum\fR frames.
163+
.TP
164+
\fBheapshot\fR[=\fImode\fR]
165+
Enable heap snapshots. \fImode\fR, if given, can be one of:
166+
.RS
167+
.TP
168+
\fBondemand\fR
169+
Only perform a heapshot when receiving a command via the command
170+
server.
171+
.TP
172+
\fInum\fR\fBgc\fR
173+
Perform a heapshot on every \fInum\fR collections of the major
174+
generation.
175+
.TP
176+
\fInum\fR\fBms\fR
177+
Perform a heapshot on a major generation collection if \fInum\fR
178+
milliseconds have passed since the last heapshot.
179+
.RE
180+
.IP
181+
If \fImode\fR is not given, a heapshot will be performed on every
182+
collection of the major generation.
183+
.TP
184+
\fBheapshot-on-shutdown\fR
185+
In addition to any other heapshot settings, also perform a heapshot
186+
on runtime shutdown.
187+
.TP
188+
\fBdebug\fR
189+
Print detailed debugging information. Most users should not use this
190+
option.
191+
.SS Command server
192+
The log profiler features a simple command server that currently is
193+
only used to trigger heapshots when using the on-demand mode. A
194+
random port will be used to listen for connections unless the
195+
\fBport\fR option is used. To trigger a heapshot, open a TCP
196+
connection to the command server and send the C string
197+
\fB"heapshot\\n"\fR.
198+
.PP
199+
The command server supports multiple simultaneous connections.
200+
.SS Managed library
201+
The log profiler comes with a managed library called
202+
\fBMono.Profiler.Log\fR. This library allows easily reading log files
203+
in managed code (e.g., C#) as well as interacting with the profiler
204+
at run-time.
205+
.PP
206+
With the ability to easily read log files, users can write all sorts
207+
of interesting analyses that might not be provided by the standard
208+
tools (e.g., \fBmprof\-report\fR(1)).
209+
.PP
210+
The \fBLogProfiler\fR class allows users to reconfigure profiler
211+
settings at run-time. For example, certain event types can be toggled
212+
on or off, the mode and frequency of heapshots and sampling can be
213+
changed, etc.
214+
.PP
215+
To use this library, simply pass \fB\-r:Mono.Profiler.Log\fR when
216+
compiling your code.
217+
.SS Example
218+
Collect GC allocation and sampling data for a program, then generate
219+
a report:
220+
.PP
221+
.nf
222+
.RS
223+
mono \-\-profile=log:alloc,sample program.exe
224+
mprof\-report output.mlpd
225+
.RE
226+
.fi
227+
.PP
228+
Perform a heapshot on every 5th collection and generate a report
229+
directly:
230+
.PP
231+
.nf
232+
.RS
233+
mono \-\-profile=log:heapshot=5gc,report program.exe
234+
.RE
235+
.fi
236+
.PP
237+
.SH COVERAGE PROFILER
238+
The code coverage profiler collects information about how often code
239+
paths are executed. This is done by instrumenting JIT-compiled code
240+
at all sequence points. On program exit, the coverage profiler
241+
collects all execution count information and outputs it to an XML
242+
file. The main use case for the coverage profiler is unit testing: By
243+
running unit test suites with the coverage profiler, it is possible
244+
to determine whether the unit tests actually cover all the code that
245+
they should.
246+
.PP
247+
By default, the coverage profiler writes its output to
248+
\fIcoverage.xml\fR. Refer to the \fImono/profiler/coverage.c\fR file
249+
in the Mono source tree for documentation on the schema.
250+
.PP
251+
Please note that the coverage profiler currently does not support
252+
instrumenting AOT-compiled code. When collecting coverage data, one
253+
may wish to run Mono with the \fB-O=-aot\fR option to disable loading
254+
AOT-compiled code.
255+
.SS Options
256+
The coverage profiler supports the following options:
257+
.TP
258+
\fBhelp\fR
259+
Print usage instructions.
260+
.TP
261+
\fBoutput\fR=[\fI+\fR|\fI#\fR|\fI|\fR]\fIfile\fR
262+
Write coverage data to \fIfile\fR. The optional modifiers are:
263+
.RS
264+
.ne 8
265+
.TP
266+
\fB+\fR
267+
The program PID is appended to the file name. For example,
268+
\fBoutput=+cov.xml\fR outputs to \fIcov.xml.1234\fR if the PID is
269+
\fB1234\fR.
270+
.TP
271+
\fB#\fR
272+
\fIfile\fR is parsed as a file descriptor number, which is opened
273+
with \fBfdopen\fR(3). This is mainly useful in embedding scenarios.
274+
.TP
275+
\fB|\fR
276+
\fIfile\fR is treated as a program name. It will be started with
277+
\fBpopen\fR(3) and the coverage data will be piped to its standard
278+
input.
279+
.RE
280+
.TP
281+
\fBcovfilter-file\fR=\fIfile\fR
282+
Supply a coverage filter file. This option can be given multiple
283+
times. See the \fBFilter files\fR sub-section.
284+
.SS Filter files
285+
Filter files can be used to pick and choose which types should be
286+
considered for coverage instrumentation. A filter file consists of a
287+
series of lines of the form:
288+
.PP
289+
.nf
290+
.RS
291+
\fB+\fR|\fB\-\fR\fB[\fR\fIimage_name\fR\fB]\fR\fItype_name_prefix\fR
292+
.RE
293+
.fi
294+
.PP
295+
Here, \fIimage_name\fR is something like \fBmscorlib\fR.
296+
\fItype_name_prefix\fR can be something like \fBSystem.Int32\fR for
297+
a specific type or \fBSystem.App\fR to pick all types starting with
298+
\fBApp\fR in the \fBSystem\fR namespace.
299+
.PP
300+
Lines starting with \fB+\fR indicate that a type should be
301+
instrumented for coverage, whereas lines starting with \fB\-\fR
302+
indicate the opposite. Lines starting with \fB+\fR always override
303+
lines starting with \fB\-\fR regardless of the order they appear in.
304+
.PP
305+
Lines not starting with either character are ignored. This can be
306+
used to write comments. For example, this is a valid file:
307+
.PP
308+
.nf
309+
.RS
310+
# Ignore coverage in network-related code, except HTTP client code.
311+
-[MyProgram]MyProgram.Net
312+
+[MyProgram]MyProgram.Net.Http.HttpClient
313+
.RE
314+
.fi
315+
.SS Example
316+
Coverage data for a program can be collected like this:
317+
.PP
318+
.nf
319+
.RS
320+
mono \-O=\-aot \-\-profile=coverage:output=cov.xml program.exe
321+
.RE
322+
.fi
323+
.PP
324+
\fIcov.xml\fR will now contain the coverage data.
325+
.SH AOT PROFILER
326+
The AOT profiler will record which generic instantiations a program
327+
makes use of and save the information to a specified file. This data
328+
can then be used by the AOT compiler to compile those generic
329+
instantiations ahead of time to reduce program startup time.
330+
.PP
331+
By default, the AOT profiler writes its output to
332+
\fIoutput.aotprofile\fR. Refer to the \fImono/profiler/aot.h\fR file
333+
in the Mono source tree for documentation on the AOT profiler's file
334+
format.
335+
.SS Options
336+
The AOT profiler supports the following options:
337+
.TP
338+
\fBhelp\fR
339+
Print usage instructions.
340+
.TP
341+
\fBoutput\fR=[\fI+\fR|\fI#\fR|\fI|\fR]\fIfile\fR
342+
Write output data to \fIfile\fR. The optional modifiers are:
343+
.RS
344+
.ne 8
345+
.TP
346+
\fB+\fR
347+
The program PID is appended to the file name. For example,
348+
\fBoutput=+out.aotprofile\fR outputs to \fIout.aotprofile.1234\fR if
349+
the PID is \fB1234\fR.
350+
.TP
351+
\fB#\fR
352+
\fIfile\fR is parsed as a file descriptor number, which is opened
353+
with \fBfdopen\fR(3). This is mainly useful in embedding scenarios.
354+
.TP
355+
\fB|\fR
356+
\fIfile\fR is treated as a program name. It will be started with
357+
\fBpopen\fR(3) and the log data will be piped to its standard input.
358+
.RE
359+
.TP
360+
\fBverbose\fR
361+
Print detailed debugging information. Most users should not use this
362+
option.
363+
.SS Example
364+
A profile can be collected and used like this:
365+
.PP
366+
.nf
367+
.RS
368+
mono \-\-profile=aot:output=program.aotprofile program.exe
369+
mono \-\-aot=profile=program.aotprofile program.exe
370+
mono program.exe
371+
.RE
372+
.fi
373+
.PP
374+
.SH SEE ALSO
375+
\fBmono\fR(1), \fBmprof\-report\fR(1)

0 commit comments

Comments
 (0)