Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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:

       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://www.freebsd.org/cgi/man.cgi?query=mono-profilers&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help