![]() |
Arm MAP Metric Plugin Interface
Metric Plugin Interface for MAP
|
Welcome to the documentation for the Arm MAP Metric Plugin Interface. The Arm MAP Metric Plugin Interface enables metric plugin libraries to be written and compiled as a small shared library. This library can then used by Arm MAP and other profilers implementing the Metric Plugin API.
The documentation of this interface is composed of the following sections:
The metric plugin template documentation specifies which functions must be implemented to create a metric plugin library. This consists of one or more metric getter functions that return the values of a metric when called, a pair of optional initialization and cleanup functions called when a metric library shared object is loaded or unloaded, and optional routines which are called when the sampler is initialized and when sampling ends.
The metric plugin API documents the functions that may be used by metric libraries. The implementation of these functions must be provided by any profiler that intends to use metric plugin libraries to obtain data.
Metric plugin libraries are installed into profilers by providing an XML metric definition file describing what metrics are provided by a metric library, and how those metrics are to be used and displayed.
Arm Performance Reports can be extended with one or more partial report sections, where the metrics to be displayed can be defined by the user, enabling custom metrics to be part of the default .html and the .txt report files generated by Arm Performance Reports.
There are two main issues to keep in mind when writing a metric plugin library:
Arm MAP aims to avoid adding overhead to the runtime of the program that it profiles. The insertion of a comparatively small amount of overhead can get magnified when MPI communications between a large number of processes are taken into account. For this reason, metric getters should return values as fast as possible, and long-running operations should be avoided unless in the allinea_plugin_initialize() or allinea_plugin_cleanup() functions.
Arm MAP does its sampling from inside a signal handler. This signal may interrupt any operation, including basic C library functions such as malloc
or printf
. It is possible for a signal to interrupt an operation in such a way that for the duration of the signal handler some data structures are left in an inconsistent state. If the code in the signal handler then uses such a data structure (for example, makes another malloc
call) then the program could deadlock, crash, or otherwise behave in an unpredictable way. To prevent this, code called in a metric plugin getter method must avoid making any function calls that are not async-signal safe (allocating memory being the prime example). For convenience, the Metric Plugin API includes versions of many common functions that are safe to use inside signal handlers (and subsequently, from metric getter functions).
See the example metric plugin implementation custom1.c and the corresponding definition file custom1.xml.
To profile using metric plugin libraries, ensure your profiler is setup to:
divideBySampleTime
attribute set to true
in their XML definition (see <metric>).Custom metrics are not supported in Arm MAP and Arm Performance Reports when the Arm MAP sampler is statically linked.
Many of the Metric Plugin API functions are provided for convenience to make async-signal safety less troublesome. If your profiler never makes metric getter calls from signal handlers, but instead always calls them from well-defined (safe) points in user-code, then your API implementation can pass the calls to the libc
functions (i.e. allinea_safe_malloc() -> malloc
. Similarly I/O related utility functions, such as allinea_safe_read() and allinea_safe_write(), are provided for I/O metric count correctness. If your profiler does not track I/O, then those functions can similarly pass the calls to the corresponding libc
implementation.