-.SH LOGGING PROFILER
-.PP
-The
-.I logging profiler
-is a general purpose profiler that can track many different kinds of
-events and logs those into a file as the program executes. This is
-different than previous profilers in Mono that kept the information in
-memory and rendered a summary of the results when the program shut
-down.
-.PP
-Using the logging profiler means that useful information can be
-gathered for long-running applications, applications that terminate
-abormally (crashes, segfaults, complicated tear down processes) or
-when no data about the shutdown is required.
-.PP
-The data collected by the running threads is kept independent of each
-other to minimize the runtime overhead and the information dumped into
-the log at regular intervals.
-.PP
-A sample use is very simple:
-.nf
- $ mono --profile=logging program.exe
-
- $ mprof-decoder program.mprof
-.fi
-.PP
-In the above example the logging profiler is used in its default mode
-that merely records GC statistics for the execution of program.exe.
-The profiling data collected is stored in the file program.mprof. The
-mprof-decoder tool is then used to analyze the data.
-.PP
-You can instruct the logging profiler to record different one or more
-sets of events. These are the modes supported:
-.IP
-.I Statistical Profiling (stat)
-the program instruction pointer is periodically sampled to determine
-where the program is spending most of its time. Statistical
-profiling has a very low impact on a running application and it is
-very useful to get a general picture of where time is being spent on a
-program.
-.IP
-If call chains are requested, for each sample the profiler gets a
-partial stack trace (limited by the specified 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
-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:statistical\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 perform statistical profiling:
-.nf
-
- mono --profile=logging:stat program.exe
-.fi
-.PP
-To perform statistical profiling, inspecting call chains up to depth 8:
-.nf
-
- mono --profile=logging:stat=8 program.exe
-.fi
-.PP
-To profile allocations (by default the call stack will be analized for
-each allocation, producing detailed caller method attribution infornation):
-.nf
-
- mono --profile=logging:allocations program.exe
-.fi
-.PP
-To profile garbage collection activity at a high level (collection time and objects freed
-at each collection for each class are reported, but heap snapshots are not saved to disk):
-.nf
-
- mono --profile=logging:allocations-summary program.exe
-.fi
-.PP
-To perform heap profiling taking heap snapshots:
-.nf
-
- mono --profile=logging:heap=all program.exe
-.fi
-.PP
-To write the resulting data to a different file:
-.nf
-
- mono --profile=logging:output=mydata.mprof 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, or to examine heap
-snapshots and allocations in detail \fImprof-heap-viewer(1)\fR.
-.PP
-The operating modes described above are the default ones, and are sufficient
-to use the profiler.
-.PP
-To further customize the profiler behavior there are more options, described
-below.
-.PP
-These options can be individually enabled and disabled prefixing them
-with an (optional) '+' character or a '-' character. For instance,
-the "allocations" option by default records also the full call stack
-at each allocation. If only the caller is wanted, one should use
-"allocations,-save-allocation-stack", or to disable call tracking
-completely (making the profiler less intrusive)
-"allocations,-save-allocation-caller,-save-allocation-stack". In
-practice the "allocation" option by default behaves like
-"allocations,save-allocation-caller,save-allocation-stack", but the
-user can tune this to his needs.
-.PP
-These are all the available options, 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.
-.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).
-By default this also implies "+save-allocation-caller" and
-"+save-allocation-stack".
-.TP
-\fIsave-allocation-caller\fR, \fIsac\fR
-Save the direct caller of each allocation. The profiler filters out wrapper
-methods, and also recognizes if the allocation has been performed by the
-runtime while jitting a method.
-.TP
-\fIsave-allocation-stack\fR, \fIsas\fR
-Save the full managed execution stack at each allocation.
-While the "sac" option saves the direct caller, this one records the whole
-stack trace.
-Note that in the call stack the wrapper methods are not filtered out.
-Anyway the "sac" 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[=ARG]\fR, \fIheap[=ARG]\fR or \fIh[=ARH]\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
-If the value of ARG is
-.B all,
-a heap snapshot is taken at each collection.
-.PP
-If the value is an integer
-.B n,
-a snapshot will be taken at the first
-.B n
-collections (like setting
-.B gcd=n
-);
-.PP
-If no additional argument is given to the heap option, the only way to take
-heap snapshots is to requeste them using the runtime socket based command
-interface described below (see "Profiler activity control").
-.PP
-Heap profiling also enables full allocation profiling (with call
-stacks), and each allocation can be related to its corresponding
-object in the snapshots, enabling investigations like "find all
-objects of a given class allocated by a given method and still live at
-a given collection, and then find all objects referencing them".
-.PP
-This kind of heap snapshot analysis is performed using the mprof-heap-viewer(1)
-application.
-.PP
-The number of heap snapshots taken (and the moment in which they are taken)
-can be further customized with the following options:
-.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
-These options exist because it can happen that the user wants to investigate
-what happens during collections but without forcing a collection using the
-command interface, because forcing a collection alters the program behavior.
-Of course it is possible to simply take a snapshot at every collection, but
-in some workloads this is could not be feasible (too much data).
-So we have this "garbage collection dumps" counter to control how many
-snapshots to take.
-.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
-\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.
-.TP
-\fIcommand-port=port\fR or \fIcp=port\fR (where port is an integer between
-1024 nd 65535):
-Choose a TCP port where the profiler will listen for user commands.
-The protocol is ASCII based and line oriented (one line per command), and the
-profiler answers with one line containing either "OK" or "ERROR" to each
-received command.
-.PP
-The user can telnet to this port and give commands manually, or a GUI can
-use this facility to control the profiler at runtime.
-.PP
-The available commands are:
-.TP
-\fIenable\fR: Enables the profiler.
-.TP
-\fIdisable\fR: Disables the profiler.
-.TP
-\fIheap-snapshot\fR: Takes a heap snapshot now (forces a full garbage collection).
-.TP
-\fIheap-snapshot-counter=arg\fR: Set the counter of the next heap snapshots
-that must be taken, where arg can be "all" (take a snapshot at every
-collection), "none" (do not take snapshots), or an integer "n" (take a heap
-snapshot for the next "n" collections).
-.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 the HeapShot profiler, but there is no UI to process this
-information.
-.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
-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
-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.