-.SH LOGGING PROFILER
-.PP
-The
-.I logging profiler
-will eventually replace the default profiler as it is more complete
-and encompasses the functionality of all the other profilers for Mono.
-It supports the following execution modes:
-.IP
-.I Statistical:
-the program instruction pointer is periodically sampled (it works also with
-unmanaged functions). If call chains are requested, for each sample the
-profiler gets a partial stack trace (up to a desired depth) so that
-caller-callee information is available.
-.IP
-.I Instrumenting:
-each method enter and exit is logged with a timestamp; further processing of
-the data can show the methods that took the longer to execute, with complete
-accounting for callers and callees. However, this way of profiling is rather
-intrusive and slows down the application significantly.
-.IP
-.I Allocation:
-each allocation is logged.
-.IP
-.I Allocation summary:
-shows, for each collection, a summary of the heap contents broken down by
-class (for each class the number of allocated and released objects is
-given, together with their aggregated size in bytes).
-.IP
-.I Heap snapshot mode:
-dumps the whole heap contents at every collection (or at user specified
-collections). It is also possible to request a collection and snapshot dump
-with a signal.
-.PP
-Moreover, other events can be logged and analyzed, like jit time for each
-method, load and unload for assemblies, modules and and individual classes,
-and appdomain and thread creation and destruction.
-.PP
-Instead of reporting the collected
-information at the end of the execution of the program, this profiler logs
-all the events periodically into a file during program execution.
-To minimize the performance impact with multi-threaded applications,
-the logging uses per-thread buffers that are routinely saved to disk.
-.PP
-The output file contains compressed events, to process the data you should
-use tools like the "Mono.Profiler" tool provided on the Mono SVN
-repository.
-.PP
-This profiler is activated passing the \fB--profile=logging\fR option to
-the mono runtime, and is controlled attaching further options, like
-\fB--profile=logging:stat\fR for doing statistical profiling (multiple
-options are separated by commas).
-.PP
-As a quick primer, here are a few examples of the most common usage modes:
-.PP
-To write the resulting data to "mydata.mprof" (defaults to statistical
-profiling):
-.nf
-
- mono --profile=logging:o=mydata.mprof program.exe
-.fi
-.PP
-To perform statistical profiling, inspecting call chains up to depth 8:
-.nf
-
- mono --profile=logging:s=8 program.exe
-.fi
-.PP
-To profile allocations with caller method attribution:
-.nf
-
- mono --profile=logging:a,ts program.exe
-.fi
-.PP
-To profile garbage collection activity (collection time and objects freed
-at each collection):
-.nf
-
- mono --profile=logging:g,as program.exe
-.fi
-.PP
-Then you would need to invoke the decoder \fImprof-decoder(1)\fR
-on the output file to see the profiling results.
-.PP
-These are all the available oprions, organized by category:
-.PP
-\fBExecution profiling modes\fR
-.RS
-.ne 8
-.TP
-\fIstatistical\fR, \fIstat\fR or \fIs\fR
-Performs statistical profiling. This is a lightweight profiling
-mechanism and it has a much lower overhead than the \fIenter-leave\fR
-profiling as it works by sampling where the program is spending its
-time by using a timer.
-If specified with \fIs=<number>\fR, also inspect call chains up to level
-<number>.
-.TP
-\fIenter-leave\fR, \fIcalls\fR or \fIc\fR
-Measure the time spent inside each method call, this is done by
-logging the time when a method enters and when the method leaves.
-This can be a time consuming operation.
-.TP
-\fIjit\fR, \fIj\fR
-Collect information about time spent by the JIT engine compiling
-methods.
-.TP
-\fItrack-stack\fR, \fIts\fR
-Track the execution stack. By itself this option does nothing, but it
-enables more detailed reporting in other options (because the profiler
-will use the stack data).
-.ne
-.RE
-.PP
-\fBAllocation profiling modes\fR
-.RS
-.ne 8
-.TP
-\fIallocations\fR, \fIalloc\fR or \fIa\fR
-Collect information about each allocation (object class and size).
-If combined with the "ts" option, for each allocation the profiler will
-also show the responsible method (and also correctly dintinguish allocations
-performed during JIT time).
-These information are also available when combining the "a" and "c" options,
-but since "c" is much more intrusive "ts" should be preferred.
-.TP
-\fIsave-allocation-stack\fR, \fIsas\fR
-Save the execution stack at each allocation. While the "ts" option saves the
-direct caller, this one records the whole stack trace. Note that for technical
-reasons the decoder will correctly ignore wrapper methods only using the data
-saved by the "ts" option (the stack traces still contain all the wrappers).
-Anyway the "ts" and "sas" options can be combined, and the decoder will
-attribute the allocation to the correct method even if the wrapper is at the
-top of the stack trace.
-.TP
-\fIallocations-summary\fR or \fIas\fR
-At each collection dump a summary
-of the heap contents (for each class, the number and collective size of all
-live and freed heap objects). This very lightweight compared to full heap
-snapshots.
-.TP
-\fIunreachable\fR, \fIfree\fR or \fIf\fR
-Performs a lightweight profile of the garbage collector. On each
-collection performed by the GC, the list of unreachable objects is
-recorded, and for each object the class and size is provided. This
-information can be used to compute the heap size broken down by class
-(combined with "a" can give the same information of "as", but the log
-file contains info about each individual object, while in "as" the
-processing is done directly at runtime and the log file contains only
-the summarized data broken down by class).
-.TP
-\fIgc\fR or \fIg\fR
-Measure the time spent in each collection, and also trace heap resizes.
-.TP
-\fIheap-shot\fR, \fIheap\fR or \fIh\fR
-Performs full heap profiling. In this case on each
-collection a full heap snapshot is recorded to disk.
-Inside the snapshots, each object reference is still represented so
-that it's possible to investigate who is responsible for keeping objects
-alive.
-.PP
-The actual production of heap snapshots could produce large log files,
-so it can be controlled in three ways:
-.TP
-\fIgc-dumps=N\fR, \fIgc-d=N\fR, \fIgcd=N\fR
-states the number of snapshots that must be dumped (since the application
-starts). Zero means no dumps at all, -1 means dump at all collections.
-.TP
-\fIgc-signal=<signal>\fR, \fIgc-s\fR or \fIgcs\fR
-(where <signal> is one of "SIGUSR1", "SIGUSR2", or "SIGPROF")
-specifies a signal that will immediately trigger a collection and a dump.
-.TP
-\fIgc-commands=FILE\fR, \fIgc-c=FILE\fR or \fIgcc=FILE\fR
-specify a "command file". The file must contain an integer value in ASCII
-form, and the profiler will stat it at every collection.
-If it has been modified it will interpret its contents as a \fIgcd=N\fR
-option value, and dump the required number of snapshots from that moment
-onwards.
-If the file is present at application startup it takes precedence over an
-eventual \fIgcd=N\fR option.
-.ne
-.RE
-.PP
-\fBProfiler activity control\fR
-.RS
-.ne 8
-.TP
-\fIoutput=FILE\fR, \fIout=FILE\fR or \fIo=FILE\fR
-Use this option to provide the output file name for the profile log.
-If this option is not specified, it will default to "<program-name>.mprof".
-.TP
-\fIoutput-suffix=SUFFIX\fR, \fIsuffix=SUFFIX\fR or \fIos=SUFFIX\fR: makes
-the output file name equals to "<program-name>-SUFFIX.mprof".
-.TP
-\fIstart-enabled\fR or \fIse\fR: start with the profiler active
-(which is the default).
-.TP
-\fIstart-disabled\fR or \fIsd\fR: start with the profiler inactive.
-.TP
-\fItoggle-signal=<SIGNAL>\fR or \fIts=<SIGNAL>\fR (where <SIGNAL>
-is one of SIGUSR1, SIGUSR2 or SIGPROF): Choose a signal that will be used to
-toggle the profiler activity on and off. This way you can decide to profile
-only portions of the applicatopn lifetime (for instance, you can decide to
-avoid profiling an initial setup phase using \fIsd\fR, and enable the
-profiler later delivering the signal to the application).
-.TP
-\fIforce-accurate-timer\fR (or \fIfac\fR): the profiler by default uses
-rtdsc to acquire timestamps for frequent events, but this can be imprecise;
-using this option you force the use of "gettimeofday" at every event, which
-is more accurate but much slower.
-.ne
-.RE
-.PP
-\fBInternal buffer sizes\fR
-.RS
-.ne 8
-.TP
-\fIper-thread-buffer-size=N\fR, \fItbs=N\fR
-Use to specify the number of events that a thread buffer
-can hold. When the thread buffer is full, a log block is
-written to disk.
-.Sp
-This defaults to tbs=10000.
-.TP
-\fIstatistical-thread-buffer-size=N\fR, \fIsbs=N\fR
-The number of statistical samples that
-are held in memory before they are dumped to disk (the system does
-double-buffering and the statistical samples are written by a helper
-thread, so the statistical profiler never stops and is able to profile
-the profiler itself).
-.Sp
-This defaults to sbs=10000.
-.TP
-\fIwrite-buffer-size\fR, \fIwbs\fR
-Specifies the size in bytes of the internal write buffers.
-.Sp
-This defaults to wbs=1024.
-.ne
-.RE
-.PP
-In its current state, this profiler can also perform heap analysis (like
-heap-shot), and the decoder is already able to read the data, however
-the user interface for this feature is experimental (the
-\fImprof-heap-viewer\fR tool in the mono-tools module).
-.PP
-Another known issue is that if the timer is not strictly monotonic (like
-rtdsc), differences between times can underflow (they are handled as
-unsigned integers) and weird numbers can show up in the logs.
-.PP
-Finally, it can happen that when exceptions are thrown the profiler temporarily
-loses track of the execution stack and misattributes the caller for a few
-allocations (and method execution time).
-.PP
-More explanations are provided here: "http://www.mono-project.com/LoggingProfiler".
-.SH EXTERNAL PROFILERS
-There are a number of external profilers that have been developed for
-Mono, we will update this section to contain the profilers.
-.PP
-The heap Shot profiler can track all live objects, and references to
-these objects, and includes a GUI tool, this is our recommended
-profiler.
-To install you must download the profiler
-from Mono's SVN:
-.nf
- svn co svn://anonsvn.mono-project.com/source/trunk/heap-shot
- cd heap-shot
- ./autogen
- make
- make install
-.fi
-.PP
-See the included documentation for details on using it.
-.PP
-The Live Type profiler shows at every GC iteration all of the live
-objects of a given type. To install you must download the profiler
-from Mono's SVN:
-.nf
- svn co svn://anonsvn.mono-project.com/source/trunk/heap-prof
- cd heap-prof
- ./autogen
- make
- make install
-.fi
-.PP
-To use the profiler, execute:
-.nf
- mono --profile=desc-heap program.exe
-.fi
-.PP
-The output of this profiler looks like this:
-.nf
- Checkpoint at 102 for heap-resize
- System.MonoType : 708
- System.Threading.Thread : 352
- System.String : 3230
- System.String[] : 104
- Gnome.ModuleInfo : 112
- System.Object[] : 160
- System.Collections.Hashtable : 96
- System.Int32[] : 212
- System.Collections.Hashtable+Slot[] : 296
- System.Globalization.CultureInfo : 108
- System.Globalization.NumberFormatInfo : 144
-.fi
-.PP
-The first line describes the iteration number for the GC, in this case
-checkpoint 102.
-.PP
-Then on each line the type is displayed as well as the number of bytes
-that are being consumed by live instances of this object.
-.PP
-The AOT profiler is used to feed back information to the AOT compiler
-about how to order code based on the access patterns for pages. To
-use it, use:
-.nf
- mono --profile=aot program.exe
-.fi
-The output of this profile can be fed back into Mono's AOT compiler to
-order the functions on the disk to produce precompiled images that
-have methods in sequential pages.