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 *sampling* or *statistical* 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%).
## Basic profiler usage
`mono --profile=log:nocalls program.exe`
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 as well.
+to each allocation because at each object allocation a stack trace is collected if
+full enter/leave information is not available.
To periodically collect heap shots (and exclude method and allocation events) use the
following options (making sure you run with the sgen garbage collector):
`mono --gc=sgen --profile=log:heapshot program.exe`
+To perform a sampling profiler run, use the *sample* option:
+
+`mono --profile=log:sample program.exe`
+
## Profiler option documentation
By default the *log* profiler will gather all the events provided by the Mono runtime
control this behaviour. *calls* enables method enter/leave events if they were disabled
by another option like *heapshot*.
-* *heapshot*: collect heap shot data at each major collection. The frequency of the
-heap shots can be changed with the *hsmode* option below. When this option is used
+* *heapshot[=MODE]*: collect heap shot data at each major collection. The frequency of the
+heap shots can be changed with the *MODE* 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.
-
-* *hsmode=MODE*: modify the default heap shot frequency according to MODE.
-hsmode can be used multiple times with different modes: in that case a heap shot is
+The optional parameter *MODE* 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:
* *NUM*ms: perform a heap shot if at least *NUM* milliseconds passed since
the last one.
- * *NUM*gc: perform a heap shot every *NUM* garbage collections (either
- minor or major).
-
+ * *NUM*gc: perform a heap shot every *NUM* major garbage collections
+ * *ondemand*: perform a heap shot when such a command is sent to the
+ control port
+
+* *sample[=TYPE[/FREQ]]*: collect statistical samples of the program behaviour. The
+default is to collect a 1000 times per second the instruction pointer. This is
+equivalent to the value "cycles/1000" for *TYPE*. On some systems, like with recent
+Linux kernels, it is possible to cause the sampling to happen for other events
+provided by the performance counters of the cpu. In this case, *TYPE* can be one of:
+ * *cycles*: processor cycles
+ * *instr*: executed instructions
+ * *cacherefs*: cache references
+ * *cachemiss*: cache misses
+ * *branches*: executed branches
+ * *branchmiss*: mispredicted branches
* *time=TIMER*: use the TIMER timestamp mode. TIMER can have the following values:
* *fast*: a usually faster but possibly more inaccurate timer
* *maxframes=NUM*: when a stack trace needs to be performed, collect *NUM* frames
-at the most.
+at the most. The default is 8.
* *calldepth=NUM*: ignore method enter/leave events when the call chain depth is
bigger than NUM.
* *zip*: automatically compress the output data in gzip format.
* *output=OUTSPEC*: instead of writing the profiling data to the output.mlpd file,
-do according to *OUTSPEC*:
+substitute *%p* in *OUTSPEC* with the current process id and *%t* with the current
+date and time, then do according to *OUTSPEC*:
* if *OUTSPEC* begins with a *|* character, execute the rest as a program
and feed the data to its standard input
- * otherwise write the data the the named file
+ * if *OUTSPEC* begins with a *-* character, use the rest of OUTSPEC as
+ the filename, but force overwrite any existing file by that name
+ * otherwise write the data the the named file: note that is a file by that
+ name already exists, a warning is issued and profiling is disabled.
* *report*: the profiling data is sent to mprof-report, which will print a summary
-report. This is equivalent to the option: `output=mprof-report -`.
+report. This is equivalent to the option: `output=mprof-report -`. If the *output*
+option is specified as well, the report will be written to the output file instead of
+the console.
+
+* *port=PORT*: 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:
+ * *heapshot*: perform a heapshot as soon as possible
## Analyzing the profile data
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
-*maxframes=0* option.
+*maxframes=0* profiler option. Note that the profiler will collect up to 8
+frames by default at specific events when the *nocalls* option is used, so
+in that case, if more stack frames are required in mprof-report, a bigger
+value for maxframes when profiling must be used, too.
+
+The *--traces* 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.
### Sort order for methods and allocations
where the report names R1, R2 etc. can be:
+* *header*: information about program startup and profiler version
+* *jit*: JIT compiler information
+* *sample*: statistical sampling information
* *gc*: garbage collection information
* *alloc*: object allocation information
* *call*: method profiling information
`--verbose`
+### Track individual objects
+
+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 *--track* option as follows:
+
+`--track=0xaddr1[,0xaddr2,...]`
+
+The reported info (if available in the data file), will be class name, size,
+creation time, stack trace of creation (with the *--traces* option), etc.
+If heapshot data is available it will be possible to also track what other objects
+reference one of the listed addresses.
+
+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 *--find=FINDSPEC* option. FINDSPEC can be one of the
+following:
+
+* *S:SIZE*: where the object is selected if it's size is at least *SIZE*
+* *T:NAME*: where the object is selected if *NAME* partially matches its class name
+
+This option can be specified multiple times with one of the different kinds
+of FINDSPEC. For example, the following:
+
+`--find=S:10000 --find=T:Byte[]`
+
+will find all the byte arrays that are at least 10000 bytes in size.
+
+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.
+
### Saving a profiler report
By default mprof-report will print the summary data to the console.
slow down significantly, usually 10 to 20 times slower. There are several
ways to reduce the impact of the profiler on the program execution.
+### Use the statistical sampling mode
+
+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 it's execution time without significantly
+perturbing its behaviour.
+
### Collect less data
Collecting method enter/leave events can be very expensive, especially in programs
completely, by setting it to 0.
The other major source of data is the heapshot profiler option: especially
-if the managed heap is big, since every object needs to be inspected. The *hsmode*
-option can be used to reduce the frequency of the heap shots.
+if the managed heap is big, since every object needs to be inspected. The *MODE*
+parameter of the *heapshot* option can be used to reduce the frequency of the heap
+shots.
### Reduce the timestamp overhead
but, depending on the system, time accounting may have some level of approximation
(though statistically the data should be still fairly valuable).
-### Use a statistical profiler instead
-
-See the mono manpage for the use of a statistical (sampling) profiler.
-The *log* profiler will be enhanced to provide sampling info in the future.
-
## Dealing with the size of the data files
When collecting a lot of information about a profiled program, huge data
Allocation events can be eliminated with the *noalloc* option.
Heap shot data can also be huge: by default it is collected at each major collection.
-To reduce the frequency, you can use the *hsmode* profiler option to collect for example
+To reduce the frequency, you can specify a heapshot mode: for example to collect
every 5 collections (including major and minor):
-`hsmode=5gc`
+`heapshot=5gc`
or when at least 5 seconds passed since the last heap shot:
-`hsmode=5000ms`
+`heapshot=5000ms`
### Compressing the data
projects / mono.git / blobdiff