-.TH mprof-report 1 ""
+.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
\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=8,calldepth=100\f[]
+\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,
to the control port
.RE
.IP \[bu] 2
-\f[I]sample[=TYPE[/FREQ]]\f[]: collect statistical samples of the
+\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]cycles/100\[rq] for
-\f[I]TYPE\f[].
-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, \f[I]TYPE\f[] can be one of:
-.RS 2
-.IP \[bu] 2
-\f[I]cycles\f[]: processor cycles
-.IP \[bu] 2
-\f[I]instr\f[]: executed instructions
-.IP \[bu] 2
-\f[I]cacherefs\f[]: cache references
-.IP \[bu] 2
-\f[I]cachemiss\f[]: cache misses
+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]branches\f[]: executed branches
-.IP \[bu] 2
-\f[I]branchmiss\f[]: mispredicted branches
-.RE
-.IP \[bu] 2
-\f[I]time=TIMER\f[]: use the TIMER timestamp mode.
-TIMER can have the following values:
-.RS 2
-.IP \[bu] 2
-\f[I]fast\f[]: a usually faster but possibly more inaccurate timer
-.RE
+\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 8.
+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
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
+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, use the
-rest of OUTSPEC as the filename, but force overwrite any existing
-file by that name
+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, a warning is issued and profiling is
-disabled.
+that name already exists, it is truncated.
.RE
.IP \[bu] 2
\f[I]report\f[]: the profiling data is sent to mprof-report, which
\f[I]heapshot\f[]: perform a heapshot as soon as possible
.RE
.IP \[bu] 2
-\f[I]counters\f[]: sample counters values every 1 second. This allow
-a really lightweight way to have insight in some of the runtime key
-metrics. Counters displayed in non verbose mode are : Methods from AOT,
-Methods JITted using mono JIT, Methods JITted using LLVM, Total time
-spent JITting (sec), User Time, System Time, Total Time, Working Set,
-Private Bytes, Virtual Bytes, Page Faults and CPU Load Average (1min,
-5min and 15min).
+\f[I]nocounters\f[]: disables sampling of runtime and performance
+counters, which is normally done every 1 second.
.RE
.SS Analyzing the profile data
.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]\[em]maxframes=NUM\f[] option:
+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.
-Note that the profiler will collect up to 8 frames by default at
-specific events when the \f[I]nocalls\f[] 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.
.PP
-The \f[I]\[em]traces\f[] option also controls the reverse reference
+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
\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:
possible to track some interesting information about some specific
object addresses.
The objects are selected based on their address with the
-\f[I]\[em]track\f[] option as follows:
+\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]\[em]traces\f[] option), etc.
+\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]\[em]find=FINDSPEC\f[] option.
+\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 it's size is at
+\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[]
slower.
There are several ways to reduce the impact of the profiler on the
program execution.
-.SS Use the statistical sampling mode
-.PP
+.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
-it's execution time without significantly perturbing its behaviour.
-.SS Collect less data
-.PP
+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.
-.PP
+.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[]
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.
-.PP
-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.
+.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 Reduce the timestamp overhead
-.PP
-On many operating systems or architectures what actually slows down
-profiling is the function provided by the system to get timestamp
-information.
-The \f[I]time=fast\f[] profiler option can be usually used to speed
-up this operation, but, depending on the system, time accounting
-may have some level of approximation (though statistically the data
-should be still fairly valuable).
.SS Dealing with the size of the data files
.PP
When collecting a lot of information about a profiled program, huge
not collecting some of the more space-consuming information or by
compressing the information on the fly or by just generating a
summary report.
-.SS Reducing the amount of data
-.PP
+.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:
-.PP
+.Sp
\f[B]calldepth=10\f[]
-.PP
+.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
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.
-.PP
+.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
option.
-.PP
+.Sp
Allocation events can be eliminated with the \f[I]noalloc\f[]
option.
-.PP
+.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):
-.PP
+.Sp
\f[B]heapshot=5gc\f[]
-.PP
+.Sp
or when at least 5 seconds passed since the last heap shot:
-.PP
+.Sp
\f[B]heapshot=5000ms\f[]
-.SS Compressing the data
-.PP
+.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:
-.PP
+.Sp
\f[B]gzip\ -9\ output.mlpd\f[]
-.PP
+.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.
-.PP
+.Sp
The mprof-report program will tranparently deal with either
compressed or uncompressed data files.
-.SS Generating only a summary report
-.PP
+.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.
-.PP
+.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.
-.PP
+.Sp
For example, to print only the Monitor summary with stack trace
information, you could use it like this:
-.PP
+.Sp
\f[B]output=|mprof-report\ --reports=monitor\ --traces\ -\f[]
.SH WEB SITE
http://www.mono-project.com/docs/debug+profile/profile/profiler/
.PP
mono(1)
.SH AUTHORS
-Paolo Molaro.
-
+Paolo Molaro, Alex Rønne Petersen
projects / mono.git / blobdiff