FreeBSD Manual Pages
mono-profilers(1) General Commands Manual mono-profilers(1) NAME mono-profilers - Mono's bundled profiler modules SYNOPSIS mono --profile=log[:option,...] program.exe [args]... mono --profile=coverage[:option,...] program.exe [args]... mono --profile=aot[:option,...] program.exe [args]... DESCRIPTION Mono ships with a few profiler modules that enable most typical profil- ing scenarios. This page describes each of them in the sections below. 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 mprof-report(1) or the Xamarin Profiler. By default, the log profiler writes its output to output.mlpd. Refer to the mono/profiler/log.h file in the Mono source tree for documenta- tion on the log profiler's file format. A default invocation of the log profiler gathers only basic data: Meta- data 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, statisti- cal sampling, heap snapshotting (heapshots), or method entry and exit instrumentation. See the Options sub-section. 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 zip and report options can help deal with this.) Options The log profiler supports the following options: help Print usage instructions. output=[+|#||]file Write log data to file. The optional modifiers are: + The program PID is appended to the file name. For exam- ple, output=+out.mlpd outputs to out.mlpd.1234 if the PID is 1234. # file is parsed as a file descriptor number, which is opened with fdopen(3). This is mainly useful in embedding scenarios. | file is treated as a program name. It will be started with popen(3) and the log data will be piped to its stan- dard input. report Generate a report directly instead of writing the log data to a file. If this option is used together with the output option, the report will be written to the specified file instead of the log data. zip Compress the output file with gzip(1). port=port Use port to listen for command server connections. See the Com- mand server sub-section. nodefaults Disables pre Mono 5.6 compatibility. In particular, this dis- ables exception events and performance counter sampling by de- fault. 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. This option will be the default in a future version of the log profiler. [no]event Enable or disable gathering data for event, which can be one of: exception Exception throw and clause (catch, finally, etc) evalua- tion events. Enabled by default unless nodefaults is used. monitor Monitor lock contention, acquisition, and release events. gc GC start, progress, stop, and resize events. gcalloc GC allocation events. gcmove GC move events. gcroot GC root report events. Generated on every collection if enabled, unless nodefaults is used, in which case, they're only generated on heapshots. gchandle GC handle creation and deletion events. finalization Object finalization events. counter Performance counter sample events. Enabled by default un- less nodefaults is used. jit JIT code buffer events. alloc Alias for gc, gcalloc, and gcmove. legacy Alias for exception, monitor, gc, gcmove, gcroot, gchan- dle, finalization, and counter. sample[-real][=freq] Enable statistical sampling. The default is to sample at a fre- quency of 100 Hz, but freq can be used to override this. By default, sampling uses process time (i.e., the more work a process does, the more samples are collected). The -real variant uses wall clock time instead. Wall clock time is better for pro- grams that are I/O-bound. maxsamples=num Limit the number of reusable sample events to num 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. calls Enable method entry and exit instrumentation. This is an alter- native to statistical sampling when you need more precise infor- mation. Note that this mode is extremely heavy and can slow most programs to a crawl. callspec=spec Limit method entry and exit instrumentation to methods matching the specified call spec. This uses the same syntax as the --trace option for mono(1), so refer to that page for more in- formation. calldepth=num Limit method entry and exit event collection to a call depth of num. maxframes=num Limit backtraces in various events (including statistical sam- ples) to num frames. heapshot[=mode] Enable heap snapshots. mode, if given, can be one of: ondemand Only perform a heapshot when receiving a command via the command server or when triggered through the managed li- brary. numgc Perform a heapshot on every num collections of the major generation. numms Perform a heapshot on a major generation collection if num milliseconds have passed since the last heapshot. If mode is not given, a heapshot will be performed on every col- lection of the major generation. heapshot-on-shutdown In addition to any other heapshot settings, also perform a heap- shot on runtime shutdown. debug Print detailed debugging information. Most users should not use this option. Command server The log profiler features a simple command server that currently is only used to trigger manual heapshots (typcally when using the on-de- mand mode, but also usable with the other modes). A random port will be used to listen for connections unless the port option is used. To trig- ger a heapshot, open a TCP connection to the command server and send the C string "heapshot\n". The command server supports multiple simultaneous connections. Managed library The log profiler comes with a managed library called Mono.Profiler.Log. This library allows easily reading log files in managed code (e.g., C#) as well as interacting with the profiler at run-time. 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., mprof-report(1)). The LogProfiler 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. Heapshots can also be triggered manually. To use this library, simply pass -r:Mono.Profiler.Log when compiling your code. Example Collect GC allocation and sampling data for a program, then generate a report: mono --profile=log:alloc,sample program.exe mprof-report output.mlpd Perform a heapshot on every 5th collection and generate a report di- rectly: mono --profile=log:heapshot=5gc,report program.exe 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. By default, the coverage profiler writes its output to coverage.xml. Refer to the mono/profiler/coverage.c file in the Mono source tree for documentation on the schema. Please note that the coverage profiler currently does not support in- strumenting AOT-compiled code. When collecting coverage data, one may wish to run Mono with the -O=-aot option to disable loading AOT-com- piled code. Options The coverage profiler supports the following options: help Print usage instructions. output=[+|#||]file Write coverage data to file. The optional modifiers are: + The program PID is appended to the file name. For exam- ple, output=+cov.xml outputs to cov.xml.1234 if the PID is 1234. # file is parsed as a file descriptor number, which is opened with fdopen(3). This is mainly useful in embedding scenarios. | file is treated as a program name. It will be started with popen(3) and the coverage data will be piped to its standard input. covfilter-file=file Supply a coverage filter file. This option can be given multiple times. See the Filter files sub-section. Filter files Filter files can be used to pick and choose which types should be con- sidered for coverage instrumentation. A filter file consists of a se- ries of lines of the form: +|-[image_name]type_name_prefix Here, image_name is something like mscorlib. type_name_prefix can be something like System.Int32 for a specific type or System.App to pick all types starting with App in the System namespace. Lines starting with + indicate that a type should be instrumented for coverage, whereas lines starting with - indicate the opposite. Lines starting with + always override lines starting with - regardless of the order they appear in. Lines not starting with either character are ignored. This can be used to write comments. For example, this is a valid file: # Ignore coverage in network-related code, except HTTP client code. -[MyProgram]MyProgram.Net +[MyProgram]MyProgram.Net.Http.HttpClient Example Coverage data for a program can be collected like this: mono -O=-aot --profile=coverage:output=cov.xml program.exe cov.xml will now contain the coverage data. 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 instanti- ations ahead of time to reduce program startup time. By default, the AOT profiler writes its output to output.aotprofile. Refer to the mono/profiler/aot.h file in the Mono source tree for docu- mentation on the AOT profiler's file format. Options The AOT profiler supports the following options: duration=num Profile only NUM seconds of runtime and then write the data. help Print usage instructions. output=[+|#||]file Write output data to file. The optional modifiers are: + The program PID is appended to the file name. For exam- ple, output=+out.aotprofile outputs to out.aotpro- file.1234 if the PID is 1234. # file is parsed as a file descriptor number, which is opened with fdopen(3). This is mainly useful in embedding scenarios. | file is treated as a program name. It will be started with popen(3) and the log data will be piped to its stan- dard input. verbose Print detailed debugging information. Most users should not use this option. Example A profile can be collected and used like this: mono --profile=aot:output=program.aotprofile program.exe mono --aot=profile=program.aotprofile program.exe mono program.exe SEE ALSO mono(1), mprof-report(1) mono-profilers(1)
NAME | SYNOPSIS | DESCRIPTION | LOG PROFILER | COVERAGE PROFILER | AOT PROFILER | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mono-profilers&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>