1mono-profilers(1)           General Commands Manual          mono-profilers(1)
2
3
4

NAME

6       mono-profilers - Mono's bundled profiler modules
7

SYNOPSIS

9       mono --profile=log[:option,...] program.exe [args]...
10
11       mono --profile=coverage[:option,...] program.exe [args]...
12
13       mono --profile=aot[:option,...] program.exe [args]...
14

DESCRIPTION

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

LOG PROFILER

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
24       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
28       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
35       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
39   Options
40       The log profiler supports the following options:
41
42       help   Print usage instructions.
43
44       output=[+|#||]file
45              Write log data to file. The optional modifiers are:
46
47              +      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
51              #      file  is  parsed  as  a  file descriptor number, which is
52                     opened with fdopen(3). This is mainly useful in embedding
53                     scenarios.
54
55              |      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
59       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
64       zip    Compress the output file with gzip(1).
65
66       port=port
67              Use port to listen for command server connections. See the  Com‐
68              mand server sub-section.
69
70       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
77              This  option  will be the default in a future version of the log
78              profiler.
79
80       [no]event
81              Enable or disable gathering data for event, which can be one of:
82
83              exception
84                     Exception throw and clause (catch, finally, etc)  evalua‐
85                     tion  events.  Enabled  by  default  unless nodefaults is
86                     used.
87
88              monitor
89                     Monitor lock contention, acquisition, and release events.
90
91              gc     GC start, progress, stop, and resize events.
92
93              gcalloc
94                     GC allocation events.
95
96              gcmove GC move events.
97
98              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
102              gchandle
103                     GC handle creation and deletion events.
104
105              finalization
106                     Object finalization events.
107
108              counter
109                     Performance counter sample  events.  Enabled  by  default
110                     unless nodefaults is used.
111
112              jit    JIT code buffer events.
113
114              alloc  Alias for gc, gcalloc, and gcmove.
115
116              legacy Alias  for exception, monitor, gc, gcmove, gcroot, gchan‐
117                     dle, finalization, and counter.
118
119       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
123              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
128       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
135       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
140       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
146       calldepth=num
147              Limit method entry and exit event collection to a call depth  of
148              num.
149
150       maxframes=num
151              Limit  backtraces  in various events (including statistical sam‐
152              ples) to num frames.
153
154       heapshot[=mode]
155              Enable heap snapshots. mode, if given, can be one of:
156
157              ondemand
158                     Only perform a heapshot when receiving a command via  the
159                     command  server  or  when  triggered  through the managed
160                     library.
161
162              numgc  Perform a heapshot on every num collections of the  major
163                     generation.
164
165              numms  Perform  a  heapshot  on a major generation collection if
166                     num milliseconds have passed since the last heapshot.
167
168              If mode is not given, a heapshot will be performed on every col‐
169              lection of the major generation.
170
171       heapshot-on-shutdown
172              In addition to any other heapshot settings, also perform a heap‐
173              shot on runtime shutdown.
174
175       debug  Print detailed debugging information. Most users should not  use
176              this option.
177
178   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
186       The command server supports multiple simultaneous connections.
187
188   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
193       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
197       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
202       To  use  this  library, simply pass -r:Mono.Profiler.Log when compiling
203       your code.
204
205   Example
206       Collect GC allocation and sampling data for a program, then generate  a
207       report:
208
209              mono --profile=log:alloc,sample program.exe
210              mprof-report output.mlpd
211
212       Perform  a  heapshot  on  every  5th  collection  and generate a report
213       directly:
214
215              mono --profile=log:heapshot=5gc,report program.exe
216

COVERAGE PROFILER

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
226       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
230       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
235   Options
236       The coverage profiler supports the following options:
237
238       help   Print usage instructions.
239
240       output=[+|#||]file
241              Write coverage data to file. The optional modifiers are:
242
243              +      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
247              #      file  is  parsed  as  a  file descriptor number, which is
248                     opened with fdopen(3). This is mainly useful in embedding
249                     scenarios.
250
251              |      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
255       covfilter-file=file
256              Supply a coverage filter file. This option can be given multiple
257              times. See the Filter files sub-section.
258
259   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
264              +|-[image_name]type_name_prefix
265
266       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
270       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
275       Lines  not starting with either character are ignored. This can be used
276       to write comments. For example, this is a valid file:
277
278              # Ignore coverage in network-related code, except HTTP client code.
279              -[MyProgram]MyProgram.Net
280              +[MyProgram]MyProgram.Net.Http.HttpClient
281
282   Example
283       Coverage data for a program can be collected like this:
284
285              mono -O=-aot --profile=coverage:output=cov.xml program.exe
286
287       cov.xml will now contain the coverage data.
288

AOT PROFILER

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
295       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
299   Options
300       The AOT profiler supports the following options:
301
302       help   Print usage instructions.
303
304       output=[+|#||]file
305              Write output data to file. The optional modifiers are:
306
307              +      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
311              #      file  is  parsed  as  a  file descriptor number, which is
312                     opened with fdopen(3). This is mainly useful in embedding
313                     scenarios.
314
315              |      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
319       verbose
320              Print  detailed debugging information. Most users should not use
321              this option.
322
323   Example
324       A profile can be collected and used like this:
325
326              mono --profile=aot:output=program.aotprofile program.exe
327              mono --aot=profile=program.aotprofile program.exe
328              mono program.exe
329

SEE ALSO

331       mono(1), mprof-report(1)
332
333
334
335                                                             mono-profilers(1)
Impressum