| blob | 169d3ddb190c0a0426132b56b23279fec51b2e62 |
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 or when triggered through the managed library.
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 manual heapshots (typcally when using the
194 on-demand mode, but also usable with the other modes). A random port
195 will be used to listen for connections unless the \fBport\fR option
196 is used. To trigger a heapshot, open a TCP connection to the command
197 server and send the C string \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. Heapshots can also be triggered manually.
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 \fBduration\fR=\fInum\fR
339 Profile only NUM seconds of runtime and then write the data.
340 .TP
341 \fBhelp\fR
342 Print usage instructions.
343 .TP
344 \fBoutput\fR=[\fI+\fR|\fI#\fR|\fI|\fR]\fIfile\fR
345 Write output data to \fIfile\fR. The optional modifiers are:
346 .RS
347 .ne 8
348 .TP
349 \fB+\fR
350 The program PID is appended to the file name. For example,
351 \fBoutput=+out.aotprofile\fR outputs to \fIout.aotprofile.1234\fR if
352 the PID is \fB1234\fR.
353 .TP
354 \fB#\fR
355 \fIfile\fR is parsed as a file descriptor number, which is opened
356 with \fBfdopen\fR(3). This is mainly useful in embedding scenarios.
357 .TP
358 \fB|\fR
359 \fIfile\fR is treated as a program name. It will be started with
360 \fBpopen\fR(3) and the log data will be piped to its standard input.
361 .RE
362 .TP
363 \fBverbose\fR
364 Print detailed debugging information. Most users should not use this
365 option.
366 .SS Example
367 A profile can be collected and used like this:
368 .PP
369 .nf
370 .RS
371 mono \-\-profile=aot:output=program.aotprofile program.exe
372 mono \-\-aot=profile=program.aotprofile program.exe
373 mono program.exe
374 .RE
375 .fi
376 .PP
377 .SH SEE ALSO
378 \fBmono\fR(1), \fBmprof\-report\fR(1)