diff options
author | Alex Rønne Petersen <alpeters@microsoft.com> | 2017-11-22 14:31:57 +0300 |
---|---|---|
committer | Alex Rønne Petersen <alpeters@microsoft.com> | 2017-11-23 16:16:03 +0300 |
commit | c7f9875f279990b37bca5678fe0a56eaa4903b9f (patch) | |
tree | 611b65eba20ac63d0aa8ce4e3a6595567e8dcf7b /man | |
parent | cbe30987b038a6a253f50a2d8aa1f29980ab8c17 (diff) |
[man] Rewrite the profiler-related man pages.
* Separate profiler module documentation into a new mono-profilers(1) page.
* Add documentation for the aot and coverage profilers.
* Rewrite the mprof-report(1) page to only talk about mprof-report itself.
* Rewrite and update the profiler-related sections of mono(1).
* Conform to man page formatting conventions.
Diffstat (limited to 'man')
-rw-r--r-- | man/Makefile.am | 3 | ||||
-rw-r--r-- | man/mono-profilers.1 | 375 | ||||
-rw-r--r-- | man/mono.1 | 217 | ||||
-rw-r--r-- | man/mprof-report.1 | 678 |
4 files changed, 604 insertions, 669 deletions
diff --git a/man/Makefile.am b/man/Makefile.am index ef449a4d594..e59e357db5e 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -58,6 +58,7 @@ man_MANS = \ mono-configuration-crypto.1 \ ccrewrite.1 \ cccheck.1 \ - mono-symbolicate.1 + mono-symbolicate.1 \ + mono-profilers.1 EXTRA_DIST = $(man_MANS) diff --git a/man/mono-profilers.1 b/man/mono-profilers.1 new file mode 100644 index 00000000000..97b1aced7e1 --- /dev/null +++ b/man/mono-profilers.1 @@ -0,0 +1,375 @@ +.TH mono-profilers 1 +.SH NAME +mono\-profilers \- Mono's bundled profiler modules +.SH SYNOPSIS +\fBmono\ \-\-profile=log\fR[:\fIoption\fR,...] \fIprogram.exe\fR [\fIargs\fR]... +.PP +\fBmono\ \-\-profile=coverage\fR[:\fIoption\fR,...] \fIprogram.exe\fR [\fIargs\fR]... +.PP +\fBmono\ \-\-profile=aot\fR[:\fIoption\fR,...] \fIprogram.exe\fR [\fIargs\fR]... +.SH DESCRIPTION +Mono ships with a few profiler modules that enable most typical +profiling scenarios. This page describes each of them in the sections +below. +.SH LOG PROFILER +The log profiler is Mono's general-purpose performance profiler. It +can collect a wide variety of data that can be analyzed by tools such +as \fBmprof\-report\fR(1) or the Xamarin Profiler. +.PP +By default, the log profiler writes its output to \fIoutput.mlpd\fR. +Refer to the \fImono/profiler/log.h\fR file in the Mono source tree +for documentation on the log profiler's file format. +.PP +A default invocation of the log profiler gathers only basic data: +Metadata load and unload events, thread start and stop events, +performance counter samples, exception throws, etc. Most users will +want to enable some of the heavier features such as GC allocation +recording, statistical sampling, heap snapshotting (heapshots), or +method entry and exit instrumentation. See the \fBOptions\fR +sub-section. +.PP +Note that, in most realistic scenarios, the log profiler will record +a vast amount of data. This can lead to very large log files. (The +\fBzip\fR and \fBreport\fR options can help deal with this.) +.SS Options +The log profiler supports the following options: +.TP +\fBhelp\fR +Print usage instructions. +.TP +\fBoutput\fR=[\fI+\fR|\fI#\fR|\fI|\fR]\fIfile\fR +Write log data to \fIfile\fR. The optional modifiers are: +.RS +.ne 8 +.TP +\fB+\fR +The program PID is appended to the file name. For example, +\fBoutput=+out.mlpd\fR outputs to \fIout.mlpd.1234\fR if the PID is +\fB1234\fR. +.TP +\fB#\fR +\fIfile\fR is parsed as a file descriptor number, which is opened +with \fBfdopen\fR(3). This is mainly useful in embedding scenarios. +.TP +\fB|\fR +\fIfile\fR is treated as a program name. It will be started with +\fBpopen\fR(3) and the log data will be piped to its standard input. +.RE +.TP +\fBreport\fR +Generate a report directly instead of writing the log data to a file. +If this option is used together with the \fBoutput\fR option, the +report will be written to the specified file instead of the log data. +.TP +\fBzip\fR +Compress the output file with \fBgzip\fR(1). +.TP +\fBport\fR=\fIport\fR +Use \fIport\fR to listen for command server connections. See the +\fBCommand server\fR sub-section. +.TP +\fBnodefaults\fR +Disables pre Mono 5.6 compatibility. In particular, this disables +exception events and performance counter sampling by default. It also +makes it so that GC move events won't be enabled by default when +heapshots are enabled. To use this option, it must be the first +option given to the log profiler. +.IP +This option will be the default in a future version of the log +profiler. +.TP +[\fBno\fR]\fIevent\fR +Enable or disable gathering data for \fIevent\fR, which can be one +of: +.RS +.TP +\fBexception\fR +Exception throw and clause (\fBcatch\fR, \fBfinally\fR, etc) +evaluation events. Enabled by default unless \fBnodefaults\fR is +used. +.TP +\fBmonitor\fR +Monitor lock contention, acquisition, and release events. +.TP +\fBgc\fR +GC start, progress, stop, and resize events. +.TP +\fBgcalloc\fR +GC allocation events. +.TP +\fBgcmove\fR +GC move events. +.TP +\fBgcroot\fR +GC root report events. Generated on every collection if enabled, +unless \fBnodefaults\fR is used, in which case, they're only +generated on heapshots. +.TP +\fBgchandle\fR +GC handle creation and deletion events. +.TP +\fBfinalization\fR +Object finalization events. +.TP +\fBcounter\fR +Performance counter sample events. Enabled by default unless +\fBnodefaults\fR is used. +.TP +\fBjit\fR +JIT code buffer events. +.TP +\fBalloc\fR +Alias for \fBgc\fR, \fBgcalloc\fR, and \fBgcmove\fR. +.TP +\fBlegacy\fR +Alias for \fBexception\fR, \fBmonitor\fR, \fBgc\fR, \fBgcmove\fR, +\fBgcroot\fR, \fBgchandle\fR, \fBfinalization\fR, and \fBcounter\fR. +.RE +.TP +\fBsample\fR[\fB\-real\fR][=\fIfreq\fR] +Enable statistical sampling. The default is to sample at a frequency +of 100 Hz, but \fIfreq\fR can be used to override this. +.IP +By default, sampling uses process time (i.e., the more work a process +does, the more samples are collected). The \fB-real\fR variant uses +wall clock time instead. Wall clock time is better for programs that +are I/O-bound. +.TP +\fBmaxsamples\fR=\fInum\fR +Limit the number of reusable sample events to \fInum\fR allocations. +A value of zero means no limit. By default, the value of this setting +is based on the number of CPU cores. Some tinkering with this setting +may be necessary for programs with an unusually high amount of +threads. +.TP +\fBcalls\fR +Enable method entry and exit instrumentation. This is an alternative +to statistical sampling when you need more precise information. Note +that this mode is extremely heavy and can slow most programs to a +crawl. +.TP +\fBcallspec\fR=\fIspec\fR +Limit method entry and exit instrumentation to methods matching the +specified call spec. This uses the same syntax as the \fB--trace\fR +option for \fBmono\fR(1), so refer to that page for more information. +.TP +\fBcalldepth\fR=\fInum\fR +Limit method entry and exit event collection to a call depth of +\fInum\fR. +.TP +\fBmaxframes\fR=\fInum\fR +Limit backtraces in various events (including statistical samples) to +\fInum\fR frames. +.TP +\fBheapshot\fR[=\fImode\fR] +Enable heap snapshots. \fImode\fR, if given, can be one of: +.RS +.TP +\fBondemand\fR +Only perform a heapshot when receiving a command via the command +server. +.TP +\fInum\fR\fBgc\fR +Perform a heapshot on every \fInum\fR collections of the major +generation. +.TP +\fInum\fR\fBms\fR +Perform a heapshot on a major generation collection if \fInum\fR +milliseconds have passed since the last heapshot. +.RE +.IP +If \fImode\fR is not given, a heapshot will be performed on every +collection of the major generation. +.TP +\fBheapshot-on-shutdown\fR +In addition to any other heapshot settings, also perform a heapshot +on runtime shutdown. +.TP +\fBdebug\fR +Print detailed debugging information. Most users should not use this +option. +.SS Command server +The log profiler features a simple command server that currently is +only used to trigger heapshots when using the on-demand mode. A +random port will be used to listen for connections unless the +\fBport\fR option is used. To trigger a heapshot, open a TCP +connection to the command server and send the C string +\fB"heapshot\\n"\fR. +.PP +The command server supports multiple simultaneous connections. +.SS Managed library +The log profiler comes with a managed library called +\fBMono.Profiler.Log\fR. This library allows easily reading log files +in managed code (e.g., C#) as well as interacting with the profiler +at run-time. +.PP +With the ability to easily read log files, users can write all sorts +of interesting analyses that might not be provided by the standard +tools (e.g., \fBmprof\-report\fR(1)). +.PP +The \fBLogProfiler\fR class allows users to reconfigure profiler +settings at run-time. For example, certain event types can be toggled +on or off, the mode and frequency of heapshots and sampling can be +changed, etc. +.PP +To use this library, simply pass \fB\-r:Mono.Profiler.Log\fR when +compiling your code. +.SS Example +Collect GC allocation and sampling data for a program, then generate +a report: +.PP +.nf +.RS +mono \-\-profile=log:alloc,sample program.exe +mprof\-report output.mlpd +.RE +.fi +.PP +Perform a heapshot on every 5th collection and generate a report +directly: +.PP +.nf +.RS +mono \-\-profile=log:heapshot=5gc,report program.exe +.RE +.fi +.PP +.SH COVERAGE PROFILER +The code coverage profiler collects information about how often code +paths are executed. This is done by instrumenting JIT-compiled code +at all sequence points. On program exit, the coverage profiler +collects all execution count information and outputs it to an XML +file. The main use case for the coverage profiler is unit testing: By +running unit test suites with the coverage profiler, it is possible +to determine whether the unit tests actually cover all the code that +they should. +.PP +By default, the coverage profiler writes its output to +\fIcoverage.xml\fR. Refer to the \fImono/profiler/coverage.c\fR file +in the Mono source tree for documentation on the schema. +.PP +Please note that the coverage profiler currently does not support +instrumenting AOT-compiled code. When collecting coverage data, one +may wish to run Mono with the \fB-O=-aot\fR option to disable loading +AOT-compiled code. +.SS Options +The coverage profiler supports the following options: +.TP +\fBhelp\fR +Print usage instructions. +.TP +\fBoutput\fR=[\fI+\fR|\fI#\fR|\fI|\fR]\fIfile\fR +Write coverage data to \fIfile\fR. The optional modifiers are: +.RS +.ne 8 +.TP +\fB+\fR +The program PID is appended to the file name. For example, +\fBoutput=+cov.xml\fR outputs to \fIcov.xml.1234\fR if the PID is +\fB1234\fR. +.TP +\fB#\fR +\fIfile\fR is parsed as a file descriptor number, which is opened +with \fBfdopen\fR(3). This is mainly useful in embedding scenarios. +.TP +\fB|\fR +\fIfile\fR is treated as a program name. It will be started with +\fBpopen\fR(3) and the coverage data will be piped to its standard +input. +.RE +.TP +\fBcovfilter-file\fR=\fIfile\fR +Supply a coverage filter file. This option can be given multiple +times. See the \fBFilter files\fR sub-section. +.SS Filter files +Filter files can be used to pick and choose which types should be +considered for coverage instrumentation. A filter file consists of a +series of lines of the form: +.PP +.nf +.RS +\fB+\fR|\fB\-\fR\fB[\fR\fIimage_name\fR\fB]\fR\fItype_name_prefix\fR +.RE +.fi +.PP +Here, \fIimage_name\fR is something like \fBmscorlib\fR. +\fItype_name_prefix\fR can be something like \fBSystem.Int32\fR for +a specific type or \fBSystem.App\fR to pick all types starting with +\fBApp\fR in the \fBSystem\fR namespace. +.PP +Lines starting with \fB+\fR indicate that a type should be +instrumented for coverage, whereas lines starting with \fB\-\fR +indicate the opposite. Lines starting with \fB+\fR always override +lines starting with \fB\-\fR regardless of the order they appear in. +.PP +Lines not starting with either character are ignored. This can be +used to write comments. For example, this is a valid file: +.PP +.nf +.RS +# Ignore coverage in network-related code, except HTTP client code. +-[MyProgram]MyProgram.Net ++[MyProgram]MyProgram.Net.Http.HttpClient +.RE +.fi +.SS Example +Coverage data for a program can be collected like this: +.PP +.nf +.RS +mono \-O=\-aot \-\-profile=coverage:output=cov.xml program.exe +.RE +.fi +.PP +\fIcov.xml\fR will now contain the coverage data. +.SH AOT PROFILER +The AOT profiler will record which generic instantiations a program +makes use of and save the information to a specified file. This data +can then be used by the AOT compiler to compile those generic +instantiations ahead of time to reduce program startup time. +.PP +By default, the AOT profiler writes its output to +\fIoutput.aotprofile\fR. Refer to the \fImono/profiler/aot.h\fR file +in the Mono source tree for documentation on the AOT profiler's file +format. +.SS Options +The AOT profiler supports the following options: +.TP +\fBhelp\fR +Print usage instructions. +.TP +\fBoutput\fR=[\fI+\fR|\fI#\fR|\fI|\fR]\fIfile\fR +Write output data to \fIfile\fR. The optional modifiers are: +.RS +.ne 8 +.TP +\fB+\fR +The program PID is appended to the file name. For example, +\fBoutput=+out.aotprofile\fR outputs to \fIout.aotprofile.1234\fR if +the PID is \fB1234\fR. +.TP +\fB#\fR +\fIfile\fR is parsed as a file descriptor number, which is opened +with \fBfdopen\fR(3). This is mainly useful in embedding scenarios. +.TP +\fB|\fR +\fIfile\fR is treated as a program name. It will be started with +\fBpopen\fR(3) and the log data will be piped to its standard input. +.RE +.TP +\fBverbose\fR +Print detailed debugging information. Most users should not use this +option. +.SS Example +A profile can be collected and used like this: +.PP +.nf +.RS +mono \-\-profile=aot:output=program.aotprofile program.exe +mono \-\-aot=profile=program.aotprofile program.exe +mono program.exe +.RE +.fi +.PP +.SH SEE ALSO +\fBmono\fR(1), \fBmprof\-report\fR(1) diff --git a/man/mono.1 b/man/mono.1 index 3a51db9692f..b38acfd314d 100644 --- a/man/mono.1 +++ b/man/mono.1 @@ -262,14 +262,14 @@ If the AOT compiler cannot compile a method for any reason, enabling this flag will output the skipped methods to the console. .TP .I profile=[file] -Specify a file to use for profile-guided optimization. See the "AOT PROFILING" section. To specify multiple files, include the +Specify a file to use for profile-guided optimization. See the \fBAOT profiler\fR sub-section. To specify multiple files, include the .I profile option multiple times. .TP .I profile-only AOT *only* the methods described in the files specified with the .I profile -option. See the "AOT PROFILING" section. +option. See the \fBAOT profiler\fR sub-section. .TP .I readonly-value=namespace.typename.fieldname=type/value Override the value of a static readonly field. Usually, during JIT @@ -641,14 +641,12 @@ platforms, and only when using gdb 7.0 or later. .ne .RE .TP -\fB--profile[=profiler[:profiler_args]]\fR -Turns on profiling. For more information about profiling applications -and code coverage see the sections "PROFILING" and "CODE COVERAGE" -below. +\fB\-\-profile\fR[=\fIprofiler\fR[:\fIprofiler_args\fR]]\fR +Loads a profiler module with the given arguments. For more information, +see the \fBPROFILING\fR section. .Sp -This option can be used multiple times, each time will load an -additional profiler. This allows developers to use modules that -extend the JIT through the Mono profiling interface. +This option can be used multiple times; each time will load an additional +profiler module. .TP \fB--trace[=expression]\fR Shows method names as they are invoked. By default all methods are @@ -827,128 +825,81 @@ create its own threads and return after invocation. This support allows for example debugging applications by having the csharp shell attach to running processes. .SH PROFILING -The mono runtime includes a profiler that can be used to explore -various performance related problems in your application. The -profiler is activated by passing the --profile command line argument -to the Mono runtime, the format is: -.nf - - --profile[=profiler[:profiler_args]] - -.fi -Mono has a built-in profiler called 'default' (and is also the default -if no arguments are specified), but developers can write custom -profilers, see the section "CUSTOM PROFILERS" for more details. -.PP -If a -.I profiler -is not specified, the default profiler is used. -.Sp -The -.I profiler_args -is a profiler-specific string of options for the profiler itself. -.Sp -The default profiler accepts the following options 'alloc' to profile -memory consumption by the application; 'time' to profile the time -spent on each routine; 'jit' to collect time spent JIT-compiling methods -and 'stat' to perform sample statistical profiling. -If no options are provided the default is 'alloc,time,jit'. -.PP -By default the -profile data is printed to stdout: to change this, use the 'file=filename' -option to output the data to filename. -.Sp -For example: -.nf - - mono --profile program.exe - -.fi -.Sp -That will run the program with the default profiler and will do time -and allocation profiling. -.Sp -.nf - - mono --profile=default:stat,alloc,file=prof.out program.exe - -.fi -Will do sample statistical profiling and allocation profiling on -program.exe. The profile data is put in prof.out. -.Sp -Note that the statistical profiler has a very low overhead and should -be the preferred profiler to use (for better output use the full path -to the mono binary when running and make sure you have installed the -addr2line utility that comes from the binutils package). -.SH LOG PROFILER -This is the most advanced profiler. +The Mono runtime includes a profiler API that dynamically loaded +profiler modules and embedders can use to collect performance-related +data about an application. Profiler modules are loaded by passing the +\fB\-\-profile\fR command line argument to the Mono runtime. .PP -The Mono \f[I]log\f[] profiler can be used to collect a lot of -information about a program running in the Mono runtime. -This data can be used (both while the process is running and later) -to do analyses of the program behaviour, determine resource usage, -performance issues or even look for particular execution patterns. +Mono ships with a few profiler modules, of which the \fBlog\fR profiler +is the most feature-rich. It is also the default profiler if the +\fIprofiler\fR argument is not given, or if \fBdefault\fR is given. +It is possible to write your own profiler modules; see the +\fBCustom profilers\fR sub-section. +.SS Log profiler +The log profiler can be used to collect a lot of information about +a program running in the Mono runtime. This data can be used (both +while the process is running and later) to do analyses of the +program behavior, determine resource usage, performance issues or +even look for particular execution patterns. .PP This is accomplished by logging the events provided by the Mono -runtime through the profiling interface and periodically writing -them to a file which can be later inspected with the mprof-report(1) -tool. +runtime through the profiler API and periodically writing them to a +file which can later be inspected with the \fBmprof\-report\fR(1) +tool. .PP -More information about how to use the log profiler is available on the -mprof-report(1) page. -.SH CUSTOM PROFILERS -Mono provides a mechanism for loading other profiling modules which in -the form of shared libraries. These profiling modules can hook up to -various parts of the Mono runtime to gather information about the code -being executed. +More information about how to use the log profiler is available on +the \fBmono\-profilers\fR(1) page, under the \fBLOG PROFILER\fR +section, as well as the \fBmprof\-report\fR(1) page. +.SS Coverage profiler +The code coverage profiler can instrument a program to help determine +which classes, methods, code paths, etc are actually executed. This +is most useful when running a test suite to determine whether the +tests actually cover the code they're expected to. .PP -To use a third party profiler you must pass the name of the profiler -to Mono, like this: -.nf - - mono --profile=custom program.exe - -.fi -.PP -In the above sample Mono will load the user defined profiler from the -shared library `mono-profiler-custom.so'. This profiler module must -be on your dynamic linker library path. -.PP -A list of other third party profilers is available from Mono's web -site (www.mono-project.com/docs/advanced/performance-tips/) +More information about how to use the coverage profiler is available +on the \fBmono\-profilers\fR(1) page, under the \fBCOVERAGE +PROFILER\fR section. +.SS AOT profiler +The AOT profiler can help improve startup performance by logging +which generic instantiations are used by a program, which the AOT +compiler can then use to compile those instantiations ahead of time +so that they won't have to be JIT compiled at startup. .PP -Custom profiles are written as shared libraries. The shared library -must be called `mono-profiler-NAME.so' where `NAME' is the name of -your profiler. +More information about how to use the AOT profiler is available on +the \fBmono\-profilers\fR(1) page, under the \fBAOT PROFILER\fR +section. +.SS Custom profilers +Custom profiler modules can be loaded in exactly the same way as the +standard modules that ship with Mono. They can also access the same +profiler API to gather all kinds of information about the code being +executed. .PP -For a sample of how to write your own custom profiler look in the -Mono source tree for in the samples/profiler.c. -.SH CODE COVERAGE -Mono ships with a code coverage module in the \f[I]coverage\f[] profiler. -To enable it, pass \fB--profile=coverage\fR to your mono invocation. It -will by default output a coverage.xml in the current directory. Use -\fBmono --profile=coverage:help sample.exe\fR for more information on the -different options. -.SH AOT PROFILING -You can improve startup performance by using the AOT profiler. +For example, to use a third-party profiler called \fBcustom\fR, you +would load it like this: .PP -Typically the AOT compiler (\fBmono --aot\fR) will not generate code -for generic instantiations. To solve this, you can run Mono with the -AOT profiler to find out all the generic instantiations that are used, -and then instructing the AOT compiler to produce code for these. -.PP -This command will run the specified app.exe and produce the -\fBout.aotprof\fR file with the data describing the generic -instantiations that are needed: .nf - $ mono --profile=aot:output=out.aotprof app.exe +.RS +mono --profile=custom program.exe +.RE .fi .PP -Once you have this data, you can pass this to Mono's AOT compiler to -instruct it to generate code for it: +You could also pass arguments to it: +.PP .nf - $ mono --aot=profile=out.aotprof +.RS +mono --profile=custom:arg1,arg2=arg3 program.exe +.RE .fi +.PP +In the above example, Mono will load the profiler from the shared +library called \fIlibmono\-profiler\-custom.so\fR (name varies based +on platform, e.g., \fIlibmono\-profiler\-custom.dylib\fR on OS X). +This profiler module must be on your dynamic linker library path +(\fBLD_LIBRARY_PATH\fR on most systems, \fBDYLD_LIBRARY_PATH\fR on +OS X). +.PP +For a sample of how to write your own custom profiler, look at the +\fIsamples/profiler/sample.c\fR file in the Mono source tree. .SH DEBUGGING AIDS To debug managed applications, you can use the .B mdb @@ -1545,29 +1496,6 @@ directive instead, like this: .fi See mod_mono(8) for more details. - -Additionally. Mono includes a profiler module which allows one to track what -adjustements to file paths IOMAP code needs to do. The tracking code reports -the managed location (full stack trace) from which the IOMAP-ed call was made and, -on process exit, the locations where all the IOMAP-ed strings were created in -managed code. The latter report is only approximate as it is not always possible -to estimate the actual location where the string was created. The code uses simple -heuristics - it analyzes stack trace leading back to the string allocation location -and ignores all the managed code which lives in assemblies installed in GAC as well as in the -class libraries shipped with Mono (since they are assumed to be free of case-sensitivity -issues). It then reports the first location in the user's code - in most cases this will be -the place where the string is allocated or very close to the location. The reporting code -is implemented as a custom profiler module (see the "PROFILING" section) and can be loaded -in the following way: -.fi -.Sp -.nf - - mono --profile=iomap yourapplication.exe - -.fi -Note, however, that Mono currently supports only one profiler module -at a time. .TP \fBMONO_LLVM\fR When Mono is using the LLVM code generation backend you can use this @@ -2024,8 +1952,11 @@ http://www.mono-project.com/community/help/mailing-lists/ http://www.mono-project.com .SH SEE ALSO .PP -certmgr(1), cert-sync(1), csharp(1), gacutil(1), mcs(1), mdb(1), monodis(1), -mono-config(5), mprof-report(1), pdb2mdb(1), xsp(1), mod_mono(8). +\fBcertmgr\fR(1), \fBcert-sync\fR(1), \fBcsharp\fR(1), +\fBgacutil\fR(1), \fBmcs\fR(1), \fBmonodis\fR(1), +\fBmono-config\fR(5), \fBmono\-profilers\fR(1), +\fBmprof\-report\fR(1), \fBpdb2mdb\fR(1), \fBxsp\fR(1), +\fBmod_mono\fR(8) .PP For more information on AOT: http://www.mono-project.com/docs/advanced/aot/ diff --git a/man/mprof-report.1 b/man/mprof-report.1 index 45ea4f77b88..eafa78187f8 100644 --- a/man/mprof-report.1 +++ b/man/mprof-report.1 @@ -1,531 +1,159 @@ -.de Sp -.if t .sp .5v -.if n .sp -.. -.TH mprof-report 1 "" -.SH The Mono log profiler -.PP -The Mono \f[I]log\f[] profiler can be used to collect a lot of -information about a program running in the Mono runtime. -This data can be used (both while the process is running and later) -to do analyses of the program behaviour, determine resource usage, -performance issues or even look for particular execution patterns. -.PP -This is accomplished by logging the events provided by the Mono -runtime through the profiling interface and periodically writing -them to a file which can be later inspected with the command line -\f[I]mprof-report\f[] program or with a GUI (not developed yet). -.PP -The events collected include (among others): -.IP \[bu] 2 -method enter and leave -.IP \[bu] 2 -object allocation -.IP \[bu] 2 -garbage collection -.IP \[bu] 2 -JIT compilation -.IP \[bu] 2 -metadata loading -.IP \[bu] 2 -lock contention -.IP \[bu] 2 -exceptions -.PP -In addition, the profiler can periodically collect info about all -the objects present in the heap at the end of a garbage collection -(this is called heap shot and currently implemented only for the -sgen garbage collector). -Another available profiler mode is the \f[I]sampling\f[] or -\f[I]statistical\f[] mode: periodically the program is sampled and -the information about what the program was busy with is saved. -This allows to get information about the program behaviour without -degrading its performance too much (usually less than 10%). -.SS Basic profiler usage -.PP -The simpler way to use the profiler is the following: -.PP -\f[B]mono\ --profile=log\ program.exe\f[] -.PP -At the end of the execution the file \f[I]output.mlpd\f[] will be -found in the current directory. -A summary report of the data can be printed by running: -.PP -\f[B]mprof-report\ output.mlpd\f[] -.PP -With this invocation a huge amount of data is collected about the -program execution and collecting and saving this data can -significantly slow down program execution. -If saving the profiling data is not needed, a report can be -generated directly with: -.PP -\f[B]mono\ --profile=log:report\ program.exe\f[] -.PP -If the information about allocations is not of interest, it can be -excluded: -.PP -\f[B]mono\ --profile=log:noalloc\ program.exe\f[] -.PP -On the other hand, if method call timing is not important, while -allocations are, the needed info can be gathered with: -.PP -\f[B]mono\ --profile=log:nocalls\ program.exe\f[] -.PP -You will still be able to inspect information about the sequence of -calls that lead to each allocation because at each object -allocation a stack trace is collected if full enter/leave -information is not available. -.PP -To periodically collect heap shots (and exclude method and -allocation events) use the following options (making sure you run -with the sgen garbage collector): -.PP -\f[B]mono\ --gc=sgen\ --profile=log:heapshot\ program.exe\f[] -.PP -To perform a sampling profiler run, use the \f[I]sample\f[] option: -.PP -\f[B]mono\ --profile=log:sample\ program.exe\f[] -.SS Profiler option documentation -.PP -By default the \f[I]log\f[] profiler will gather all the events -provided by the Mono runtime and write them to a file named -\f[I]output.mlpd\f[]. -When no option is specified, it is equivalent to using: -.PP -\f[B]--profile=log:calls,alloc,output=output.mlpd,maxframes=32,calldepth=100\f[] -.PP -The following options can be used to modify this default behaviour. -Each option is separated from the next by a \f[B],\f[] character, -with no spaces and all the options are included after the -\f[I]log:\f[] profile module specifier. -.IP \[bu] 2 -\f[I]help\f[]: display concise help info about each available -option -.IP \[bu] 2 -\f[I][no]alloc\f[]: \f[I]noalloc\f[] disables collecting object -allocation info, \f[I]alloc\f[] enables it if it was disabled by -another option like \f[I]heapshot\f[]. -.IP \[bu] 2 -\f[I][no]calls\f[]: \f[I]nocalls\f[] disables collecting method -enter and leave events. -When this option is used at each object allocation and at some -other events (like lock contentions and exception throws) a stack -trace is collected by default. -See the \f[I]maxframes\f[] option to control this behaviour. -\f[I]calls\f[] enables method enter/leave events if they were -disabled by another option like \f[I]heapshot\f[]. -.IP \[bu] 2 -\f[I]heapshot[=MODE]\f[]: collect heap shot data at each major -collection. -The frequency of the heap shots can be changed with the -\f[I]MODE\f[] parameter. -When this option is used allocation events and method enter/leave -events are not recorded by default: if they are needed, they need -to be enabled explicitly. -The optional parameter \f[I]MODE\f[] can modify the default heap -shot frequency. -heapshot can be used multiple times with different modes: in that -case a heap shot is taken if either of the conditions are met. -MODE can be one of: -.RS 2 -.IP \[bu] 2 -\f[I]NUM\f[]ms: perform a heap shot if at least \f[I]NUM\f[] -milliseconds passed since the last one. -.IP \[bu] 2 -\f[I]NUM\f[]gc: perform a heap shot every \f[I]NUM\f[] major -garbage collections -.IP \[bu] 2 -\f[I]ondemand\f[]: perform a heap shot when such a command is sent -to the control port +.TH mprof-report 1 +.SH NAME +mprof\-report \- report generator for Mono's log profiler +.SH SYNOPSIS +\fBmprof\-report\fR [\fIoption\fR]... \fIfile.mlpd\fR +.SH DESCRIPTION +\fBmprof\-report\fR is the report generator for Mono's \fBlog\fR +profiler. It reads the MLPD log files produced by the log profiler +and generates a report based on the options passed to it. The +output is based on individual reports which can be turned on or off. +By default, all reports are generated in summary form (i.e., +non-verbose output). +.PP +\fBmprof\-report\fR can read both normal and \fBgzip\fR(1)-compressed +log files transparently. +.PP +For information about how to use the log profiler with a program, +see the \fBmono\-profilers\fR(1) page, under the \fBLOG PROFILER\fR +section. +.SH OPTIONS +The following options are available: +.TP +\fB\-\-help\fR +Displays usage instructions. +.TP +\fB\-\-out\fR=\fIfile\fR +Write the report output to \fIfile\fR instead of standard output. +.TP +\fB\-\-traces\fR +Show backtraces in reports when available. +.TP +\fB\-\-maxframes\fR=\fInum\fR +Limit backtraces to \fInum\fR frames. +.TP +\fB\-\-reports\fR=\fIreports\fR +Generate only the specified reports. \fIreports\fR is a +comma-separated list of reports. See the \fBREPORTS\fR section. +.TP +\fB\-\-method\-sort\fR=\fImode\fR +Sort methods according to \fImode\fR, which can be one of: +.RS +.TP +\fBtotal\fR (default) +Sort by the total amount of time spent in a method and its callees. +.TP +\fBself\fR +Sort by the amount of time spent only within a method itself. +.TP +\fBcalls\fR +Sort by the total amount of calls made to a method. .RE -.IP \[bu] 2 -\f[I]sample[=FREQ]\f[]: collect statistical samples of the -program behaviour. -The default is to collect a 100 times per second (100 Hz) the -instruction pointer. -This is equivalent to the value \[lq]100\[rq]. -A value of zero for \f[I]FREQ\f[] effectively disables sampling. -.IP \[bu] 2 -\f[I]heapshot-on-shutdown\f[]: collect heap shot data when the runtime -shuts down. -.IP \[bu] 2 -\f[I]maxframes=NUM\f[]: when a stack trace needs to be performed, -collect \f[I]NUM\f[] frames at the most. -The default is 32. -.IP \[bu] 2 -\f[I]maxsamples=NUM\f[]: stop allocating reusable sample events -once \f[I]NUM\f[] events have been allocated (a value of zero for -all intents and purposes means unlimited). By default, the value -of this setting is the number of CPU cores multiplied by 1000. This -is usually a good enough value for typical desktop and mobile apps. -If you're losing too many samples due to this default (which is -possible in apps with an unusually high amount of threads), you -may want to tinker with this value to find a good balance between -sample hit rate and performance impact on the app. The way it works -is that sample events are enqueued for reuse after they're flushed -to the output file; if a thread gets a sampling signal but there are -no sample events in the reuse queue and the profiler has reached the -maximum number of sample allocations, the sample gets dropped. So a -higher number for this setting will increase the chance that a -thread is able to collect a sample, but also necessarily means that -there will be more work done by the profiler. You can run Mono with -the \f[I]--stats\f[] option to see statistics about sample events. -.IP \[bu] 2 -\f[I]calldepth=NUM\f[]: ignore method enter/leave events when the -call chain depth is bigger than NUM. -.IP \[bu] 2 -\f[I]zip\f[]: automatically compress the output data in gzip -format. -.IP \[bu] 2 -\f[I]output=OUTSPEC\f[]: instead of writing the profiling data to -the output.mlpd file, substitute \f[I]%p\f[] in \f[I]OUTSPEC\f[] -with the current process id and \f[I]%t\f[] with the current date -and time, then do according to \f[I]OUTSPEC\f[]: -.RS 2 -.IP \[bu] 2 -If \f[I]OUTSPEC\f[] begins with a \f[I]|\f[] character, execute the -rest as a program and feed the data to its standard input. -.IP \[bu] 2 -If \f[I]OUTSPEC\f[] begins with a \f[I]#\f[] character, parse the -rest as a file descriptor number, and feed the data to this file -descriptor. -.IP \[bu] 2 -otherwise write the data the the named file: note that is a file by -that name already exists, it is truncated. +.TP +\fB\-\-alloc\-sort\fR=\fImode\fR +Sort allocations according to \fImode\fR, which can be one of: +.RS +.TP +\fBbytes\fR (default) +Sort by the amount of heap bytes occupied by all allocated objects of +a type. +.TP +\fBcount\fR +Sort by the total amount of allocations of a type. .RE -.IP \[bu] 2 -\f[I]report\f[]: the profiling data is sent to mprof-report, which -will print a summary report. -This is equivalent to the option: \f[B]output=mprof-report\ -\f[]. -If the \f[I]output\f[] option is specified as well, the report will -be written to the output file instead of the console. -.IP \[bu] 2 -\f[I]port=PORT\f[]: specify the tcp/ip port to use for the -listening command server. -Currently not available for windows. -This server is started for example when heapshot=ondemand is used: -it will read commands line by line. -The following commands are available: -.RS 2 -.IP \[bu] 2 -\f[I]heapshot\f[]: perform a heapshot as soon as possible +.TP +\fB\-\-counters\-sort\fR=\fImode\fR +Sort counters according to \fImode\fR. This alters how the +\fBcounters\fR report is presented. It can be one of: +.RS +.TP +\fBtime\fR (default) +Present a list of samples, each containing a list of counter +name-value pairs. +.TP +\fBcategory\fR +Present a list of counter names, each containing a list of sampled +values. .RE -.IP \[bu] 2 -\f[I]nocounters\f[]: disables sampling of runtime and performance -counters, which is normally done every 1 second. +.IP +This option has no effect unless \fB\-\-verbose\fR is passed. +.TP +\fB\-\-track\fR=\fIobjects\fR +Track what happens to the specified objects. \fIobjects\fR is a +comma-separated list of object addresses. +.TP +\fB\-\-find\fR=\fIspec\fR +Find and track what happens to objects matching \fIspec\fR, which can +have one of these forms: +.RS +.TP +\fBS\fR:\fIminimum_size\fR +Look for objects that are at least \fIminimum_size\fR bytes in size. +.TP +\fBT\fR:\fIname_fragment\fR +Look for objects whose type name contain \fIname_fragment\fR. .RE -.SS Analyzing the profile data -.PP -Currently there is a command line program (\f[I]mprof-report\f[]) -to analyze the data produced by the profiler. -This is ran automatically when the \f[I]report\f[] profiler option -is used. -Simply run: -.PP -\f[B]mprof-report\ output.mlpd\f[] -.PP -to see a summary report of the data included in the file. -.SS Trace information for events -.PP -Often it is important for some events, like allocations, lock -contention and exception throws to know where they happened. -Or we may want to see what sequence of calls leads to a particular -method invocation. -To see this info invoke mprof-report as follows: -.PP -\f[B]mprof-report\ --traces\ output.mlpd\f[] -.PP -The maximum number of methods in each stack trace can be specified -with the \f[I]--maxframes=NUM\f[] option: -.PP -\f[B]mprof-report\ --traces\ --maxframes=4\ output.mlpd\f[] -.PP -The stack trace info will be available if method enter/leave events -have been recorded or if stack trace collection wasn't explicitly -disabled with the \f[I]maxframes=0\f[] profiler option. -.PP -The \f[I]--traces\f[] option also controls the reverse reference -feature in the heapshot report: for each class it reports how many -references to objects of that class come from other classes. -.SS Sort order for methods and allocations -.PP -When a list of methods is printed the default sort order is based -on the total time spent in the method. -This time is wall clock time (that is, it includes the time spent, -for example, in a sleep call, even if actual cpu time would be -basically 0). -Also, if the method has been ran on different threads, the time -will be a sum of the time used in each thread. -.PP -To change the sort order, use the option: -.PP -\f[B]--method-sort=MODE\f[] -.PP -where \f[I]MODE\f[] can be: -.IP \[bu] 2 -\f[I]self\f[]: amount of time spent in the method itself and not in -its callees -.IP \[bu] 2 -\f[I]calls\f[]: the number of method invocations -.IP \[bu] 2 -\f[I]total\f[]: the total time spent in the method. -.PP -Object allocation lists are sorted by default depending on the -total amount of bytes used by each type. -.PP -To change the sort order of object allocations, use the option: -.PP -\f[B]--alloc-sort=MODE\f[] -.PP -where \f[I]MODE\f[] can be: -.IP \[bu] 2 -\f[I]count\f[]: the number of allocated objects of the given type -.IP \[bu] 2 -\f[I]bytes\f[]: the total number of bytes used by objects of the -given type -.PP -To change the sort order of counters, use the option: -.PP -\f[B]--counters-sort=MODE\f[] -.PP -where \f[I]MODE\f[] can be: -.IP \[bu] 2 -\f[I]time\f[]: sort values by time then category -.IP \[bu] 2 -\f[I]category\f[]: sort values by category then time -.SS Selecting what data to report -.PP -The profiler by default collects data about many runtime subsystems -and mprof-report prints a summary of all the subsystems that are -found in the data file. -It is possible to tell mprof-report to only show information about -some of them with the following option: -.PP -\f[B]--reports=R1[,R2...]\f[] -.PP -where the report names R1, R2 etc. -can be: -.IP \[bu] 2 -\f[I]header\f[]: information about program startup and profiler -version -.IP \[bu] 2 -\f[I]jit\f[]: JIT compiler information -.IP \[bu] 2 -\f[I]sample\f[]: statistical sampling information -.IP \[bu] 2 -\f[I]gc\f[]: garbage collection information -.IP \[bu] 2 -\f[I]alloc\f[]: object allocation information -.IP \[bu] 2 -\f[I]call\f[]: method profiling information -.IP \[bu] 2 -\f[I]metadata\f[]: metadata events like image loads -.IP \[bu] 2 -\f[I]exception\f[]: exception throw and handling information -.IP \[bu] 2 -\f[I]monitor\f[]: lock contention information -.IP \[bu] 2 -\f[I]thread\f[]: thread information -.IP \[bu] 2 -\f[I]domain\f[]: app domain information -.IP \[bu] 2 -\f[I]context\f[]: remoting context information -.IP \[bu] 2 -\f[I]heapshot\f[]: live heap usage at heap shots -.IP \[bu] 2 -\f[I]counters\f[]: counters samples -.IP \[bu] 2 -\f[I]stats\f[]: event statistics -.PP -It is possible to limit some of the data displayed to a timeframe -of the program execution with the option: -.PP -\f[B]--time=FROM-TO\f[] -.PP -where \f[I]FROM\f[] and \f[I]TO\f[] are seconds since application -startup (they can be floating point numbers). -.PP -Another interesting option is to consider only events happening on -a particular thread with the following option: -.PP -\f[B]--thread=THREADID\f[] -.PP -where \f[I]THREADID\f[] is one of the numbers listed in the thread -summary report (or a thread name when present). -.PP -By default long lists of methods or other information like object -allocations are limited to the most important data. -To increase the amount of information printed you can use the -option: -.PP -\f[B]--verbose\f[] -.SS Track individual objects -.PP -Instead of printing the usual reports from the profiler data, it is -possible to track some interesting information about some specific -object addresses. -The objects are selected based on their address with the -\f[I]--track\f[] option as follows: -.PP -\f[B]--track=0xaddr1[,0xaddr2,...]\f[] -.PP -The reported info (if available in the data file), will be class -name, size, creation time, stack trace of creation (with the -\f[I]--traces\f[] option), etc. -If heapshot data is available it will be possible to also track -what other objects reference one of the listed addresses. -.PP -The object addresses can be gathered either from the profiler -report in some cases (like in the monitor lock report), from the -live application or they can be selected with the -\f[I]--find=FINDSPEC\f[] option. -FINDSPEC can be one of the following: -.IP \[bu] 2 -\f[I]S:SIZE\f[]: where the object is selected if its size is at -least \f[I]SIZE\f[] -.IP \[bu] 2 -\f[I]T:NAME\f[]: where the object is selected if \f[I]NAME\f[] -partially matches its class name -.PP -This option can be specified multiple times with one of the -different kinds of FINDSPEC. -For example, the following: -.PP -\f[B]--find=S:10000\ --find=T:Byte[]\f[] -.PP -will find all the byte arrays that are at least 10000 bytes in -size. -.PP -Note that with a moving garbage collector the object address can -change, so you may need to track the changed address manually. -It can also happen that multiple objects are allocated at the same -address, so the output from this option can become large. -.SS Saving a profiler report -.PP -By default mprof-report will print the summary data to the console. -To print it to a file, instead, use the option: -.PP -\f[B]--out=FILENAME\f[] -.SS Dealing with profiler slowness -.PP -If the profiler needs to collect lots of data, the execution of the -program will slow down significantly, usually 10 to 20 times -slower. -There are several ways to reduce the impact of the profiler on the -program execution. -.IP "\f[I]Use the statistical sampling mode\f[]" 4 -.Sp -Statistical sampling allows executing a program under the profiler -with minimal performance overhead (usually less than 10%). -This mode allows checking where the program is spending most of -its execution time without significantly perturbing its behaviour. -.IP "\f[I]Collect less data\f[]" 4 -.Sp -Collecting method enter/leave events can be very expensive, -especially in programs that perform many millions of tiny calls. -The profiler option \f[I]nocalls\f[] can be used to avoid -collecting this data or it can be limited to only a few call levels -with the \f[I]calldepth\f[] option. -.Sp -Object allocation information is expensive as well, though much -less than method enter/leave events. -If it's not needed, it can be skipped with the \f[I]noalloc\f[] -profiler option. -Note that when method enter/leave events are discarded, by default -stack traces are collected at each allocation and this can be -expensive as well. -The impact of stack trace information can be reduced by setting a -low value with the \f[I]maxframes\f[] option or by eliminating them -completely, by setting it to 0. -.Sp -The other major source of data is the \f[I]heapshot\f[] profiler -option: especially if the managed heap is big, since every object -needs to be inspected. -The \f[I]MODE\f[] parameter of the \f[I]heapshot\f[] option can be -used to reduce the frequency of the heap shots. -.SS Dealing with the size of the data files -.PP -When collecting a lot of information about a profiled program, huge -data files can be generated. -There are a few ways to minimize the amount of data, for example by -not collecting some of the more space-consuming information or by -compressing the information on the fly or by just generating a -summary report. -.IP "\f[I]Reducing the amount of data\f[]" 4 -.Sp -Method enter/leave events can be excluded completely with the -\f[I]nocalls\f[] option or they can be limited to just a few levels -of calls with the \f[I]calldepth\f[] option. -For example, the option: -.Sp -\f[B]calldepth=10\f[] -.Sp -will ignore the method events when there are more than 10 managed -stack frames. -This is very useful for programs that have deep recursion or for -programs that perform many millions of tiny calls deep enough in -the call stack. -The optimal number for the calldepth option depends on the program -and it needs to be balanced between providing enough profiling -information and allowing fast execution speed. -.Sp -Note that by default, if method events are not recorded at all, the -profiler will collect stack trace information at events like -allocations. -To avoid gathering this data, use the \f[I]maxframes=0\f[] profiler +.IP +Both an \fBS\fR and \fBT\fR spec can be given by passing the option +twice. +.TP +\fB\-\-thread\fR=\fItid\fR +Consider only events from the thread with ID \fItid\fR. +.TP +\fB\-\-time\fR=\fIspan\fR +Consider only events occurring in the specified time span. \fIspan\fR +must be of the form \fIfrom\fR\-\fIto\fR where \fIfrom\fR and +\fIto\fR are seconds since the program started. +.TP +\fB\-\-verbose\fR +Print verbose output. +.TP +\fB\-\-debug\fR +Print extremely detailed debug output. Most users should not use this option. -.Sp -Allocation events can be eliminated with the \f[I]noalloc\f[] -option. -.Sp -Heap shot data can also be huge: by default it is collected at each -major collection. -To reduce the frequency, you can specify a heapshot mode: for -example to collect every 5 collections (including major and minor): -.Sp -\f[B]heapshot=5gc\f[] -.Sp -or when at least 5 seconds passed since the last heap shot: -.Sp -\f[B]heapshot=5000ms\f[] -.IP "\f[I]Compressing the data\f[]" 4 -.Sp -To reduce the amout of disk space used by the data, the data can be -compressed either after it has been generated with the gzip -command: -.Sp -\f[B]gzip\ -9\ output.mlpd\f[] -.Sp -or it can be compressed automatically by using the \f[I]zip\f[] -profiler option. -Note that in this case there could be a significant slowdown of the -profiled program. -.Sp -The mprof-report program will tranparently deal with either -compressed or uncompressed data files. -.IP "\f[I]Generating only a summary report\f[]" 4 -.Sp -Often it's enough to look at the profiler summary report to -diagnose an issue and in this case it's possible to avoid saving -the profiler data file to disk. -This can be accomplished with the \f[I]report\f[] profiler option, -which will basically send the data to the mprof-report program for -display. -.Sp -To have more control of what summary information is reported (or to -use a completely different program to decode the profiler data), -the \f[I]output\f[] profiler option can be used, with \f[B]|\f[] as -the first character: the rest of the output name will be executed -as a program with the data fed in on the standard input. -.Sp -For example, to print only the Monitor summary with stack trace -information, you could use it like this: -.Sp -\f[B]output=|mprof-report\ --reports=monitor\ --traces\ -\f[] -.SH WEB SITE -http://www.mono-project.com/docs/debug+profile/profile/profiler/ +.SH REPORTS +The following reports are available: +.TP +\fBheader\fR +Program startup and profiler version and operational information. +.TP +\fBjit\fR +JIT compiler statistics. +.TP +\fBgc\fR +Garbage collection and handle statistics. +.TP +\fBsample\fR +Flat statistical sampling profile. +.TP +\fBalloc\fR +Per-class GC allocation statistics and backtraces. +.TP +\fBcall\fR +Method call statistics and backtraces. +.TP +\fBmetadata\fR +Loaded images and assemblies. +.TP +\fBexception\fR +Exception statistics and backtraces. +.TP +\fBmonitor\fR +Monitor lock statistics and backtraces. +.TP +\fBthread\fR +Managed thread names. +.TP +\fBdomain\fR +Loaded application domains. +.TP +\fBcontext\fR +Loaded remoting contexts. +.TP +\fBheapshot\fR +Heap snapshot information. +.TP +\fBcounters\fR +Performance counter samples. .SH SEE ALSO -.PP -mono(1) -.SH AUTHORS -Paolo Molaro, Alex Rønne Petersen +\fBmono\fR(1), \fBmono\-profilers\fR(1) |