1mono-profilers(1) General Commands Manual mono-profilers(1)
2
6 mono-profilers - Mono's bundled profiler modules
7
9 mono --profile=log[:option,...] program.exe [args]...
10 mono --profile=coverage[:option,...] program.exe [args]...
12 mono --profile=aot[:option,...] program.exe [args]...
14
16 Mono ships with a few profiler modules that enable most typical profil‐
17 ing scenarios. This page describes each of them in the sections below.
18
20 The log profiler is Mono's general-purpose performance profiler. It can
21 collect a wide variety of data that can be analyzed by tools such as
22 mprof-report(1) or the Xamarin Profiler.
23 By default, the log profiler writes its output to output.mlpd. Refer
25 to the mono/profiler/log.h file in the Mono source tree for documenta‐
26 tion on the log profiler's file format.
27 A default invocation of the log profiler gathers only basic data: Meta‐
29 data load and unload events, thread start and stop events, performance
30 counter samples, exception throws, etc. Most users will want to enable
31 some of the heavier features such as GC allocation recording, statisti‐
32 cal sampling, heap snapshotting (heapshots), or method entry and exit
33 instrumentation. See the Options sub-section.
34 Note that, in most realistic scenarios, the log profiler will record a
36 vast amount of data. This can lead to very large log files. (The zip
37 and report options can help deal with this.)
38 Options
40 The log profiler supports the following options:
41 help Print usage instructions.
43 output=[+|#||]file
45 Write log data to file. The optional modifiers are:
46 + The program PID is appended to the file name. For exam‐
48 ple, output=+out.mlpd outputs to out.mlpd.1234 if the PID
49 is 1234.
50 # file is parsed as a file descriptor number, which is
52 opened with fdopen(3). This is mainly useful in embedding
53 scenarios.
54 | file is treated as a program name. It will be started
56 with popen(3) and the log data will be piped to its stan‐
57 dard input.
58 report Generate a report directly instead of writing the log data to a
60 file. If this option is used together with the output option,
61 the report will be written to the specified file instead of the
62 log data.
63 zip Compress the output file with gzip(1).
65 port=port
67 Use port to listen for command server connections. See the Com‐
68 mand server sub-section.
69 nodefaults
71 Disables pre Mono 5.6 compatibility. In particular, this dis‐
72 ables exception events and performance counter sampling by
73 default. It also makes it so that GC move events won't be
74 enabled by default when heapshots are enabled. To use this
75 option, it must be the first option given to the log profiler.
76 This option will be the default in a future version of the log
78 profiler.
79 [no]event
81 Enable or disable gathering data for event, which can be one of:
82 exception
84 Exception throw and clause (catch, finally, etc) evalua‐
85 tion events. Enabled by default unless nodefaults is
86 used.
87 monitor
89 Monitor lock contention, acquisition, and release events.
90 gc GC start, progress, stop, and resize events.
92 gcalloc
94 GC allocation events.
95 gcmove GC move events.
97 gcroot GC root report events. Generated on every collection if
99 enabled, unless nodefaults is used, in which case,
100 they're only generated on heapshots.
101 gchandle
103 GC handle creation and deletion events.
104 finalization
106 Object finalization events.
107 counter
109 Performance counter sample events. Enabled by default
110 unless nodefaults is used.
111 jit JIT code buffer events.
113 alloc Alias for gc, gcalloc, and gcmove.
115 legacy Alias for exception, monitor, gc, gcmove, gcroot, gchan‐
117 dle, finalization, and counter.
118 sample[-real][=freq]
120 Enable statistical sampling. The default is to sample at a fre‐
121 quency of 100 Hz, but freq can be used to override this.
122 By default, sampling uses process time (i.e., the more work a
124 process does, the more samples are collected). The -real variant
125 uses wall clock time instead. Wall clock time is better for pro‐
126 grams that are I/O-bound.
127 maxsamples=num
129 Limit the number of reusable sample events to num allocations.
130 A value of zero means no limit. By default, the value of this
131 setting is based on the number of CPU cores. Some tinkering with
132 this setting may be necessary for programs with an unusually
133 high amount of threads.
134 calls Enable method entry and exit instrumentation. This is an alter‐
136 native to statistical sampling when you need more precise infor‐
137 mation. Note that this mode is extremely heavy and can slow most
138 programs to a crawl.
139 callspec=spec
141 Limit method entry and exit instrumentation to methods matching
142 the specified call spec. This uses the same syntax as the
143 --trace option for mono(1), so refer to that page for more
144 information.
145 calldepth=num
147 Limit method entry and exit event collection to a call depth of
148 num.
149 maxframes=num
151 Limit backtraces in various events (including statistical sam‐
152 ples) to num frames.
153 heapshot[=mode]
155 Enable heap snapshots. mode, if given, can be one of:
156 ondemand
158 Only perform a heapshot when receiving a command via the
159 command server or when triggered through the managed
160 library.
161 numgc Perform a heapshot on every num collections of the major
163 generation.
164 numms Perform a heapshot on a major generation collection if
166 num milliseconds have passed since the last heapshot.
167 If mode is not given, a heapshot will be performed on every col‐
169 lection of the major generation.
170 heapshot-on-shutdown
172 In addition to any other heapshot settings, also perform a heap‐
173 shot on runtime shutdown.
174 debug Print detailed debugging information. Most users should not use
176 this option.
177 Command server
179 The log profiler features a simple command server that currently is
180 only used to trigger manual heapshots (typcally when using the on-
181 demand mode, but also usable with the other modes). A random port will
182 be used to listen for connections unless the port option is used. To
183 trigger a heapshot, open a TCP connection to the command server and
184 send the C string "heapshot\n".
185 The command server supports multiple simultaneous connections.
187 Managed library
189 The log profiler comes with a managed library called Mono.Profiler.Log.
190 This library allows easily reading log files in managed code (e.g., C#)
191 as well as interacting with the profiler at run-time.
192 With the ability to easily read log files, users can write all sorts of
194 interesting analyses that might not be provided by the standard tools
195 (e.g., mprof-report(1)).
196 The LogProfiler class allows users to reconfigure profiler settings at
198 run-time. For example, certain event types can be toggled on or off,
199 the mode and frequency of heapshots and sampling can be changed, etc.
200 Heapshots can also be triggered manually.
201 To use this library, simply pass -r:Mono.Profiler.Log when compiling
203 your code.
204 Example
206 Collect GC allocation and sampling data for a program, then generate a
207 report:
208 mono --profile=log:alloc,sample program.exe
210 mprof-report output.mlpd
211 Perform a heapshot on every 5th collection and generate a report
213 directly:
214 mono --profile=log:heapshot=5gc,report program.exe
216
218 The code coverage profiler collects information about how often code
219 paths are executed. This is done by instrumenting JIT-compiled code at
220 all sequence points. On program exit, the coverage profiler collects
221 all execution count information and outputs it to an XML file. The main
222 use case for the coverage profiler is unit testing: By running unit
223 test suites with the coverage profiler, it is possible to determine
224 whether the unit tests actually cover all the code that they should.
225 By default, the coverage profiler writes its output to coverage.xml.
227 Refer to the mono/profiler/coverage.c file in the Mono source tree for
228 documentation on the schema.
229 Please note that the coverage profiler currently does not support
231 instrumenting AOT-compiled code. When collecting coverage data, one may
232 wish to run Mono with the -O=-aot option to disable loading AOT-com‐
233 piled code.
234 Options
236 The coverage profiler supports the following options:
237 help Print usage instructions.
239 output=[+|#||]file
241 Write coverage data to file. The optional modifiers are:
242 + The program PID is appended to the file name. For exam‐
244 ple, output=+cov.xml outputs to cov.xml.1234 if the PID
245 is 1234.
246 # file is parsed as a file descriptor number, which is
248 opened with fdopen(3). This is mainly useful in embedding
249 scenarios.
250 | file is treated as a program name. It will be started
252 with popen(3) and the coverage data will be piped to its
253 standard input.
254 covfilter-file=file
256 Supply a coverage filter file. This option can be given multiple
257 times. See the Filter files sub-section.
258 Filter files
260 Filter files can be used to pick and choose which types should be con‐
261 sidered for coverage instrumentation. A filter file consists of a
262 series of lines of the form:
263 +|-[image_name]type_name_prefix
265 Here, image_name is something like mscorlib. type_name_prefix can be
267 something like System.Int32 for a specific type or System.App to pick
268 all types starting with App in the System namespace.
269 Lines starting with + indicate that a type should be instrumented for
271 coverage, whereas lines starting with - indicate the opposite. Lines
272 starting with + always override lines starting with - regardless of the
273 order they appear in.
274 Lines not starting with either character are ignored. This can be used
276 to write comments. For example, this is a valid file:
277 # Ignore coverage in network-related code, except HTTP client code.
279 -[MyProgram]MyProgram.Net
280 +[MyProgram]MyProgram.Net.Http.HttpClient
281 Example
283 Coverage data for a program can be collected like this:
284 mono -O=-aot --profile=coverage:output=cov.xml program.exe
286 cov.xml will now contain the coverage data.
288
290 The AOT profiler will record which generic instantiations a program
291 makes use of and save the information to a specified file. This data
292 can then be used by the AOT compiler to compile those generic instanti‐
293 ations ahead of time to reduce program startup time.
294 By default, the AOT profiler writes its output to output.aotprofile.
296 Refer to the mono/profiler/aot.h file in the Mono source tree for docu‐
297 mentation on the AOT profiler's file format.
298 Options
300 The AOT profiler supports the following options:
301 help Print usage instructions.
303 output=[+|#||]file
305 Write output data to file. The optional modifiers are:
306 + The program PID is appended to the file name. For exam‐
308 ple, output=+out.aotprofile outputs to out.aotpro‐
309 file.1234 if the PID is 1234.
310 # file is parsed as a file descriptor number, which is
312 opened with fdopen(3). This is mainly useful in embedding
313 scenarios.
314 | file is treated as a program name. It will be started
316 with popen(3) and the log data will be piped to its stan‐
317 dard input.
318 verbose
320 Print detailed debugging information. Most users should not use
321 this option.
322 Example
324 A profile can be collected and used like this:
325 mono --profile=aot:output=program.aotprofile program.exe
327 mono --aot=profile=program.aotprofile program.exe
328 mono program.exe
329
331 mono(1), mprof-report(1)
332 mono-profilers(1)