The profiler API can be used by dynamically loaded profiler modules to monitor different aspects of a running program. The API is also usable by embedders without having to compile a profiler module.
A profiler module is simply a shared library with a single exported function which is the entry point that Mono calls at startup. It must have the following signature:
void mono_profiler_startup_example (const char *desc)
Here, the example portion of the function name is
the name of the profiler module. It must match the shared library
name (i.e. libmono-profiler-example.so). desc
is the set of arguments that were passed from the command line.
For example, a bare bones profiler module might look like this
(example.c):
#include <mono/metadata/profiler.h>
#include <stdio.h>
struct _MonoProfiler {
int dummy;
}
static MonoProfiler profiler;
static void
runtime_inited (MonoProfiler *prof)
{
printf ("Hello World");
}
void
mono_profiler_init_example (const char *desc)
{
MonoProfilerHandle handle = mono_profiler_create (&profiler);
mono_profiler_set_runtime_initialized_callback (handle, runtime_inited);
}
To compile this module, a C compiler must be invoked in a similar fashion to this, on Linux:
gcc -fPIC -shared -o libmono-profiler-example.so example.c `pkg-config --cflags mono-2`
Or on OS X:
gcc -undefined suppress -flat_namespace -o libmono-profiler-example.so example.c `pkg-config --cflags mono-2`
You can then load the module using:
mono --profile=example hello.exe
(Note that adjusting LD_LIBRARY_PATH may be
necessary in order for the dynamic linker to find the module.)
These are the functions usable for profiling programs.
Each function has a note indicating whether they're async safe. An async safe function can be invoked in a signal handler or when the world is stopped by the GC. Conversely, a function that is not async safe must not be invoked in such a context or undefined behavior can occur (crashes, deadlocks, etc).
Some functions may only be invoked from a profiler module's init function (or prior to running managed code in the case of embedding). This is noted explicitly only if applicable to a function.
These functions are used to load and install profilers.
These functions provide access to the JIT compiler's code coverage support. This functionality can be used to collect information about how many times certain code paths have been executed.
Statistical sampling can be used to interrupt managed threads based on a certain mode and frequency for the purpose of collecting data about their current work.
One common use case for this functionality, usually referred to as call sampling, is to collect a backtrace from every thread when a sampling hit event arrives. This data can then be compiled into a report indicating where a program spends most of its time.
A callback must be registered to receive sample hit events. Please see the Callback Registration section below.
Profilers can be notified about all GC allocations performed by a program or the Mono runtime.
A callback must be registered to receive allocation events. Please see the Callback Registration section below.
The JIT compiler supports instrumenting managed method entry and exit points so that a profiler callback will be invoked.
While such callbacks by themselves have traditionally only been useful for call count profiling and the like, Mono gives these callbacks access to the arguments, locals, and return value of instrumented methods (together referred to as the 'call context'). This enables many profiling scenarios that would otherwise have required explicit hooks in the base class libraries.
Callbacks must be registered to receive method entry and exit events. Please see the Callback Registration section below.
In addition to the above functions, there's a large set of
functions for installing generic profiler event callbacks. These
are generated from C macros and so are not documented here.
Please refer to the mono/metadata/profiler.h and
mono/metadata/profiler-events.h headers for a full
listing of these.
Callback registration functions are all async safe and can be safely invoked from multiple threads at the same time, with the caveat that altering a registered callback from one thread will not immediately affect another thread that is already invoking the current callback.
The profiler API does not have the same API stability garantees that the rest of the Mono embedding API does. While a breaking change to the profiler API is extremely rare, it has happened in the past when changing the API in a backwards compatible way was deemed to be too much work for too little gain.
Therefore, developers of profiler modules may rarely need to update their code to work with new versions of the profiler API.
Developers who wish to support older versions of the API can
perform a compile time check of the
MONO_PROFILER_API_VERSION macro and maintain code
for both old and new versions.
To aid with transitioning to a new version of the profiler API, the Mono runtime will detect and reject loading profiler modules which were compiled against older profiler API versions.