6 .SH The Mono log profiler
8 The Mono \f[I]log\f[] profiler can be used to collect a lot of
9 information about a program running in the Mono runtime.
10 This data can be used (both while the process is running and later)
11 to do analyses of the program behaviour, determine resource usage,
12 performance issues or even look for particular execution patterns.
14 This is accomplished by logging the events provided by the Mono
15 runtime through the profiling interface and periodically writing
16 them to a file which can be later inspected with the command line
17 \f[I]mprof-report\f[] program or with a GUI (not developed yet).
19 The events collected include (among others):
21 method enter and leave
35 In addition, the profiler can periodically collect info about all
36 the objects present in the heap at the end of a garbage collection
37 (this is called heap shot and currently implemented only for the
38 sgen garbage collector).
39 Another available profiler mode is the \f[I]sampling\f[] or
40 \f[I]statistical\f[] mode: periodically the program is sampled and
41 the information about what the program was busy with is saved.
42 This allows to get information about the program behaviour without
43 degrading its performance too much (usually less than 10%).
44 .SS Basic profiler usage
46 The simpler way to use the profiler is the following:
48 \f[B]mono\ --profile=log\ program.exe\f[]
50 At the end of the execution the file \f[I]output.mlpd\f[] will be
51 found in the current directory.
52 A summary report of the data can be printed by running:
54 \f[B]mprof-report\ output.mlpd\f[]
56 With this invocation a huge amount of data is collected about the
57 program execution and collecting and saving this data can
58 significantly slow down program execution.
59 If saving the profiling data is not needed, a report can be
60 generated directly with:
62 \f[B]mono\ --profile=log:report\ program.exe\f[]
64 If the information about allocations is not of interest, it can be
67 \f[B]mono\ --profile=log:noalloc\ program.exe\f[]
69 On the other hand, if method call timing is not important, while
70 allocations are, the needed info can be gathered with:
72 \f[B]mono\ --profile=log:nocalls\ program.exe\f[]
74 You will still be able to inspect information about the sequence of
75 calls that lead to each allocation because at each object
76 allocation a stack trace is collected if full enter/leave
77 information is not available.
79 To periodically collect heap shots (and exclude method and
80 allocation events) use the following options (making sure you run
81 with the sgen garbage collector):
83 \f[B]mono\ --gc=sgen\ --profile=log:heapshot\ program.exe\f[]
85 To perform a sampling profiler run, use the \f[I]sample\f[] option:
87 \f[B]mono\ --profile=log:sample\ program.exe\f[]
88 .SS Profiler option documentation
90 By default the \f[I]log\f[] profiler will gather all the events
91 provided by the Mono runtime and write them to a file named
93 When no option is specified, it is equivalent to using:
95 \f[B]--profile=log:calls,alloc,output=output.mlpd,maxframes=32,calldepth=100\f[]
97 The following options can be used to modify this default behaviour.
98 Each option is separated from the next by a \f[B],\f[] character,
99 with no spaces and all the options are included after the
100 \f[I]log:\f[] profile module specifier.
102 \f[I]help\f[]: display concise help info about each available
105 \f[I][no]alloc\f[]: \f[I]noalloc\f[] disables collecting object
106 allocation info, \f[I]alloc\f[] enables it if it was disabled by
107 another option like \f[I]heapshot\f[].
109 \f[I][no]calls\f[]: \f[I]nocalls\f[] disables collecting method
110 enter and leave events.
111 When this option is used at each object allocation and at some
112 other events (like lock contentions and exception throws) a stack
113 trace is collected by default.
114 See the \f[I]maxframes\f[] option to control this behaviour.
115 \f[I]calls\f[] enables method enter/leave events if they were
116 disabled by another option like \f[I]heapshot\f[].
118 \f[I]heapshot[=MODE]\f[]: collect heap shot data at each major
120 The frequency of the heap shots can be changed with the
121 \f[I]MODE\f[] parameter.
122 When this option is used allocation events and method enter/leave
123 events are not recorded by default: if they are needed, they need
124 to be enabled explicitly.
125 The optional parameter \f[I]MODE\f[] can modify the default heap
127 heapshot can be used multiple times with different modes: in that
128 case a heap shot is taken if either of the conditions are met.
132 \f[I]NUM\f[]ms: perform a heap shot if at least \f[I]NUM\f[]
133 milliseconds passed since the last one.
135 \f[I]NUM\f[]gc: perform a heap shot every \f[I]NUM\f[] major
138 \f[I]ondemand\f[]: perform a heap shot when such a command is sent
142 \f[I]sample[=FREQ]\f[]: collect statistical samples of the
144 The default is to collect a 100 times per second (100 Hz) the
146 This is equivalent to the value \[lq]100\[rq].
147 A value of zero for \f[I]FREQ\f[] effectively disables sampling.
149 \f[I]maxframes=NUM\f[]: when a stack trace needs to be performed,
150 collect \f[I]NUM\f[] frames at the most.
153 \f[I]maxsamples=NUM\f[]: stop allocating reusable sample events
154 once \f[I]NUM\f[] events have been allocated (a value of zero for
155 all intents and purposes means unlimited). By default, the value
156 of this setting is the number of CPU cores multiplied by 1000. This
157 is usually a good enough value for typical desktop and mobile apps.
158 If you're losing too many samples due to this default (which is
159 possible in apps with an unusually high amount of threads), you
160 may want to tinker with this value to find a good balance between
161 sample hit rate and performance impact on the app. The way it works
162 is that sample events are enqueued for reuse after they're flushed
163 to the output file; if a thread gets a sampling signal but there are
164 no sample events in the reuse queue and the profiler has reached the
165 maximum number of sample allocations, the sample gets dropped. So a
166 higher number for this setting will increase the chance that a
167 thread is able to collect a sample, but also necessarily means that
168 there will be more work done by the profiler. You can run Mono with
169 the \f[I]--stats\f[] option to see statistics about sample events.
171 \f[I]calldepth=NUM\f[]: ignore method enter/leave events when the
172 call chain depth is bigger than NUM.
174 \f[I]zip\f[]: automatically compress the output data in gzip
177 \f[I]output=OUTSPEC\f[]: instead of writing the profiling data to
178 the output.mlpd file, substitute \f[I]%p\f[] in \f[I]OUTSPEC\f[]
179 with the current process id and \f[I]%t\f[] with the current date
180 and time, then do according to \f[I]OUTSPEC\f[]:
183 If \f[I]OUTSPEC\f[] begins with a \f[I]|\f[] character, execute the
184 rest as a program and feed the data to its standard input.
187 otherwise write the data the the named file: note that is a file by
188 that name already exists, a warning is issued and profiling is
192 \f[I]report\f[]: the profiling data is sent to mprof-report, which
193 will print a summary report.
194 This is equivalent to the option: \f[B]output=mprof-report\ -\f[].
195 If the \f[I]output\f[] option is specified as well, the report will
196 be written to the output file instead of the console.
198 \f[I]port=PORT\f[]: specify the tcp/ip port to use for the
199 listening command server.
200 Currently not available for windows.
201 This server is started for example when heapshot=ondemand is used:
202 it will read commands line by line.
203 The following commands are available:
206 \f[I]heapshot\f[]: perform a heapshot as soon as possible
209 \f[I]nocounters\f[]: disables sampling of runtime and performance
210 counters, which is normally done every 1 second.
212 \f[I]coverage\f[]: collect code coverage data. This implies enabling
213 the \f[I]calls\f[] option.
215 \f[I]onlycoverage\f[]: can only be used with \f[I]coverage\f[]. This
216 disables most other events so that the profiler mostly only collects
219 .SS Analyzing the profile data
221 Currently there is a command line program (\f[I]mprof-report\f[])
222 to analyze the data produced by the profiler.
223 This is ran automatically when the \f[I]report\f[] profiler option
227 \f[B]mprof-report\ output.mlpd\f[]
229 to see a summary report of the data included in the file.
230 .SS Trace information for events
232 Often it is important for some events, like allocations, lock
233 contention and exception throws to know where they happened.
234 Or we may want to see what sequence of calls leads to a particular
236 To see this info invoke mprof-report as follows:
238 \f[B]mprof-report\ --traces\ output.mlpd\f[]
240 The maximum number of methods in each stack trace can be specified
241 with the \f[I]--maxframes=NUM\f[] option:
243 \f[B]mprof-report\ --traces\ --maxframes=4\ output.mlpd\f[]
245 The stack trace info will be available if method enter/leave events
246 have been recorded or if stack trace collection wasn't explicitly
247 disabled with the \f[I]maxframes=0\f[] profiler option.
249 The \f[I]--traces\f[] option also controls the reverse reference
250 feature in the heapshot report: for each class it reports how many
251 references to objects of that class come from other classes.
252 .SS Sort order for methods and allocations
254 When a list of methods is printed the default sort order is based
255 on the total time spent in the method.
256 This time is wall clock time (that is, it includes the time spent,
257 for example, in a sleep call, even if actual cpu time would be
259 Also, if the method has been ran on different threads, the time
260 will be a sum of the time used in each thread.
262 To change the sort order, use the option:
264 \f[B]--method-sort=MODE\f[]
266 where \f[I]MODE\f[] can be:
268 \f[I]self\f[]: amount of time spent in the method itself and not in
271 \f[I]calls\f[]: the number of method invocations
273 \f[I]total\f[]: the total time spent in the method.
275 Object allocation lists are sorted by default depending on the
276 total amount of bytes used by each type.
278 To change the sort order of object allocations, use the option:
280 \f[B]--alloc-sort=MODE\f[]
282 where \f[I]MODE\f[] can be:
284 \f[I]count\f[]: the number of allocated objects of the given type
286 \f[I]bytes\f[]: the total number of bytes used by objects of the
289 To change the sort order of counters, use the option:
291 \f[B]--counters-sort=MODE\f[]
293 where \f[I]MODE\f[] can be:
295 \f[I]time\f[]: sort values by time then category
297 \f[I]category\f[]: sort values by category then time
298 .SS Selecting what data to report
300 The profiler by default collects data about many runtime subsystems
301 and mprof-report prints a summary of all the subsystems that are
302 found in the data file.
303 It is possible to tell mprof-report to only show information about
304 some of them with the following option:
306 \f[B]--reports=R1[,R2...]\f[]
308 where the report names R1, R2 etc.
311 \f[I]header\f[]: information about program startup and profiler
314 \f[I]jit\f[]: JIT compiler information
316 \f[I]sample\f[]: statistical sampling information
318 \f[I]gc\f[]: garbage collection information
320 \f[I]alloc\f[]: object allocation information
322 \f[I]call\f[]: method profiling information
324 \f[I]metadata\f[]: metadata events like image loads
326 \f[I]exception\f[]: exception throw and handling information
328 \f[I]monitor\f[]: lock contention information
330 \f[I]thread\f[]: thread information
332 \f[I]domain\f[]: app domain information
334 \f[I]context\f[]: remoting context information
336 \f[I]heapshot\f[]: live heap usage at heap shots
338 \f[I]counters\f[]: counters samples
340 \f[I]coverage\f[]: code coverage data
342 \f[I]stats\f[]: event statistics
344 It is possible to limit some of the data displayed to a timeframe
345 of the program execution with the option:
347 \f[B]--time=FROM-TO\f[]
349 where \f[I]FROM\f[] and \f[I]TO\f[] are seconds since application
350 startup (they can be floating point numbers).
352 Another interesting option is to consider only events happening on
353 a particular thread with the following option:
355 \f[B]--thread=THREADID\f[]
357 where \f[I]THREADID\f[] is one of the numbers listed in the thread
358 summary report (or a thread name when present).
360 By default long lists of methods or other information like object
361 allocations are limited to the most important data.
362 To increase the amount of information printed you can use the
366 .SS Track individual objects
368 Instead of printing the usual reports from the profiler data, it is
369 possible to track some interesting information about some specific
371 The objects are selected based on their address with the
372 \f[I]--track\f[] option as follows:
374 \f[B]--track=0xaddr1[,0xaddr2,...]\f[]
376 The reported info (if available in the data file), will be class
377 name, size, creation time, stack trace of creation (with the
378 \f[I]--traces\f[] option), etc.
379 If heapshot data is available it will be possible to also track
380 what other objects reference one of the listed addresses.
382 The object addresses can be gathered either from the profiler
383 report in some cases (like in the monitor lock report), from the
384 live application or they can be selected with the
385 \f[I]--find=FINDSPEC\f[] option.
386 FINDSPEC can be one of the following:
388 \f[I]S:SIZE\f[]: where the object is selected if its size is at
391 \f[I]T:NAME\f[]: where the object is selected if \f[I]NAME\f[]
392 partially matches its class name
394 This option can be specified multiple times with one of the
395 different kinds of FINDSPEC.
396 For example, the following:
398 \f[B]--find=S:10000\ --find=T:Byte[]\f[]
400 will find all the byte arrays that are at least 10000 bytes in
403 Note that with a moving garbage collector the object address can
404 change, so you may need to track the changed address manually.
405 It can also happen that multiple objects are allocated at the same
406 address, so the output from this option can become large.
407 .SS Saving a profiler report
409 By default mprof-report will print the summary data to the console.
410 To print it to a file, instead, use the option:
412 \f[B]--out=FILENAME\f[]
413 .SS Processing code coverage data
415 If you ran the profiler with the \f[I]coverage\f[] option, you can
416 process the collected coverage data into an XML file by running
417 mprof-report like this:
419 \f[B]mprof-report --coverage-out=coverage.xml output.mlpd\f[]
420 .SS Dealing with profiler slowness
422 If the profiler needs to collect lots of data, the execution of the
423 program will slow down significantly, usually 10 to 20 times
425 There are several ways to reduce the impact of the profiler on the
427 .IP "\f[I]Use the statistical sampling mode\f[]" 4
429 Statistical sampling allows executing a program under the profiler
430 with minimal performance overhead (usually less than 10%).
431 This mode allows checking where the program is spending most of
432 its execution time without significantly perturbing its behaviour.
433 .IP "\f[I]Collect less data\f[]" 4
435 Collecting method enter/leave events can be very expensive,
436 especially in programs that perform many millions of tiny calls.
437 The profiler option \f[I]nocalls\f[] can be used to avoid
438 collecting this data or it can be limited to only a few call levels
439 with the \f[I]calldepth\f[] option.
441 Object allocation information is expensive as well, though much
442 less than method enter/leave events.
443 If it's not needed, it can be skipped with the \f[I]noalloc\f[]
445 Note that when method enter/leave events are discarded, by default
446 stack traces are collected at each allocation and this can be
448 The impact of stack trace information can be reduced by setting a
449 low value with the \f[I]maxframes\f[] option or by eliminating them
450 completely, by setting it to 0.
452 The other major source of data is the \f[I]heapshot\f[] profiler
453 option: especially if the managed heap is big, since every object
454 needs to be inspected.
455 The \f[I]MODE\f[] parameter of the \f[I]heapshot\f[] option can be
456 used to reduce the frequency of the heap shots.
457 .SS Dealing with the size of the data files
459 When collecting a lot of information about a profiled program, huge
460 data files can be generated.
461 There are a few ways to minimize the amount of data, for example by
462 not collecting some of the more space-consuming information or by
463 compressing the information on the fly or by just generating a
465 .IP "\f[I]Reducing the amount of data\f[]" 4
467 Method enter/leave events can be excluded completely with the
468 \f[I]nocalls\f[] option or they can be limited to just a few levels
469 of calls with the \f[I]calldepth\f[] option.
470 For example, the option:
472 \f[B]calldepth=10\f[]
474 will ignore the method events when there are more than 10 managed
476 This is very useful for programs that have deep recursion or for
477 programs that perform many millions of tiny calls deep enough in
479 The optimal number for the calldepth option depends on the program
480 and it needs to be balanced between providing enough profiling
481 information and allowing fast execution speed.
483 Note that by default, if method events are not recorded at all, the
484 profiler will collect stack trace information at events like
486 To avoid gathering this data, use the \f[I]maxframes=0\f[] profiler
489 Allocation events can be eliminated with the \f[I]noalloc\f[]
492 Heap shot data can also be huge: by default it is collected at each
494 To reduce the frequency, you can specify a heapshot mode: for
495 example to collect every 5 collections (including major and minor):
497 \f[B]heapshot=5gc\f[]
499 or when at least 5 seconds passed since the last heap shot:
501 \f[B]heapshot=5000ms\f[]
502 .IP "\f[I]Compressing the data\f[]" 4
504 To reduce the amout of disk space used by the data, the data can be
505 compressed either after it has been generated with the gzip
508 \f[B]gzip\ -9\ output.mlpd\f[]
510 or it can be compressed automatically by using the \f[I]zip\f[]
512 Note that in this case there could be a significant slowdown of the
515 The mprof-report program will tranparently deal with either
516 compressed or uncompressed data files.
517 .IP "\f[I]Generating only a summary report\f[]" 4
519 Often it's enough to look at the profiler summary report to
520 diagnose an issue and in this case it's possible to avoid saving
521 the profiler data file to disk.
522 This can be accomplished with the \f[I]report\f[] profiler option,
523 which will basically send the data to the mprof-report program for
526 To have more control of what summary information is reported (or to
527 use a completely different program to decode the profiler data),
528 the \f[I]output\f[] profiler option can be used, with \f[B]|\f[] as
529 the first character: the rest of the output name will be executed
530 as a program with the data fed in on the standard input.
532 For example, to print only the Monitor summary with stack trace
533 information, you could use it like this:
535 \f[B]output=|mprof-report\ --reports=monitor\ --traces\ -\f[]
537 http://www.mono-project.com/docs/debug+profile/profile/profiler/
542 Paolo Molaro, Alex Rønne Petersen