Arm MAP Metric Plugin Interface
Metric Plugin Interface for MAP
Metric Plugin Template

The functions that must be implemented by every metric plugin library. More...

Functions

int allinea_plugin_cleanup (plugin_id_t plugin_id, void *data)
 Cleans a metric plugin being unloaded. More...
 
int allinea_plugin_initialize (plugin_id_t plugin_id, void *data)
 Initialises a metric plugin. More...
 
int mymetric_getDoubleValue (metric_id_t id, struct timespec *currentSampleTime, double *outValue)
 Example of a floating-point metric getter function. More...
 
int mymetric_getIntValue (metric_id_t id, struct timespec *currentSampleTime, uint64_t *outValue)
 Example of an integer metric getter function. More...
 
int start_profiling (plugin_id_t plugin_id)
 Called when the sampler is initialised. More...
 
int stop_profiling (plugin_id_t plugin_id)
 Called after the sampler stops sampling. More...
 

Detailed Description

The functions that must be implemented by every metric plugin library.

A metric plugin library is a small shared library that implements the functions allinea_plugin_initialize() and allinea_plugin_clean(), and is called when the shared library is loaded or unloaded. It also implements one or more functions of the form (but not necessarily of the same function name) as mymetric_getIntValue() or mymetric_getDoubleValue().

See custom1.c for an example of a metric plugin that implements this template.

See Metric Plugin API for the functions that may be called by this metric library.

See Metric Definition File for information on the format of the definition file that will inform profilers what metrics the metric plugin library may provide.

Function Documentation

int allinea_plugin_cleanup ( plugin_id_t  plugin_id,
void *  data 
)

Cleans a metric plugin being unloaded.

This function must be implemented by each metric plugin library. It is called when that plugin library is unloaded. Use this function to release any held resources (open files etc). Unlike most functions used in a metric plugin library, this is not called from a signal handler. Therefore, it is safe to make general function calls and even allocate or deallocate memory using the normal libc malloc/free new/delete functions.

Note: This will be called after metric data has been extracted and transferred to the frontend. Therefore, you may not see plugin error messages set by allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef().

Parameters
plugin_idOpaque handle for the metric plugin. Use this when making calls to allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef()
dataCurrently unused, will always be NULL
Returns
0 on success; -1 on error. A description of the error should be supplied using allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() before returning.
Examples:
backfill1.c, and custom1.c.
int allinea_plugin_initialize ( plugin_id_t  plugin_id,
void *  data 
)

Initialises a metric plugin.

This function must be implemented by each metric plugin library. It is called when that plugin library is loaded. Use this function to setup data structures and do one-off resource checks. Unlike most functions used in a metric plugin library this is not called from a signal handler. Therefore, it is safe to make general function calls and allocate or deallocate memory using the normal libc malloc/free new/delete functions.

If it can be determined that this metric plugin cannot function (e.g. the required information is not available on this machine) then it should call allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() to explain the situation then return -1.

Parameters
plugin_idOpaque handle for the metric plugin. Use this when making calls to allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef()
dataCurrently unused, will always be NULL
Returns
0 on success; -1 on error. A description of the error should be supplied using allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() before returning.
Examples:
backfill1.c, and custom1.c.
int mymetric_getDoubleValue ( metric_id_t  id,
struct timespec *  currentSampleTime,
double *  outValue 
)

Example of a floating-point metric getter function.

An example of a getter function that returns a floating point metric value. Real getter functions must be registered with the profiler using a Metric definition file. For example, this function (if it existed) would be registered by having a <metric> element along the lines of :

1 <metric id="com.allinea.metrics.myplugin.mymetric">
2  <units>%</units>
3  <dataType>double</dataType>
4  <domain>time</domain>
5  <source ref="com.allinea.metrics.myplugin_src" functionName="mymetric_getValue"/>
6  <display>
7  <description>Human readable description</description>
8  <displayName>Human readable display name</displayName>
9  <type>instructions</type>
10  <colour>green</colour>
11  </display>
12 </metric>

The most relevant line being the one containing functionName="mymetric_getValue". See Metric Definition File for more details on the format of this XML file.

Parameters
[in]idAn id used by the profiler to identify this metric. This can be used in calls to Metric Plugin API functions i.e. allinea_set_metric_error_message().
[in,out]currentSampleTimeThe current time. This time is acquired from a monotonic clock which reports the time elapsed from some fixed point in the past. It is unaffected by changes in the system clock.

This is passed in from the profiler to avoid unnecessary calls to allinea_get_current_time(). If this metric is backfilled then this time is not the current time, instead it is the time at which the sample was taken and the time the sampler is now requesting a data point for.

This parameter is additionally an out parameter and may be updated with the result from a call to allinea_get_current_time() to ensure the currentSampleTime is close to the point where the metric is read. Updating currentSampleTime from any other source is undefined. In the case of a backfilled metric, currentSampleTime does not function as an out parameter and will result in an error if it is used as such. It is safe to assume that this pointer is not NULL.

Parameters
[out]outValueThe return value to be provided to the profiler. It is safe to assume that this pointer is not NULL.
Returns
0 if a metric was written to outValue successfully, a non-zero value if there was an error. In the case of an error this function should call allinea_set_metric_error_message() before returning.
Warning
This function may have been called from inside a signal handler. Implementations must not make calls that are not async-signal safe. Do not use any function that implicitly or explicitly allocates or frees memory, or uses non-reentrant functions, with the exception of the memory allocators provided by the Metric Plugin API (for example, allinea_safe_malloc() or allinea_safe_free()). Failure to observe async-signal safety can result in deadlocks, segfaults or undefined/unpredictable behaviour.
Note
Do not implement this function! Instead implement functions with the same signature but with a more appropriate function name.
int mymetric_getIntValue ( metric_id_t  id,
struct timespec *  currentSampleTime,
uint64_t *  outValue 
)

Example of an integer metric getter function.

An example of a getter function that returns an integer metric value. Real getter functions must be registered with the profiler using a Metric definition file. For example, this function (if it existed) would be registered by having a <metric> element along the lines of :

1 <metric id="com.allinea.metrics.myplugin.mymetric">
2  <units>%</units>
3  <dataType>uint64_t</dataType>
4  <domain>time</domain>
5  <source ref="com.allinea.metrics.myplugin_src" functionName="mymetric_getValue"/>
6  <display>
7  <description>Human readable description</description>
8  <displayName>Human readable display name</displayName>
9  <type>instructions</type>
10  <colour>green</colour>
11  </display>
12 </metric>

The most relevant line being the one containing functionName="mymetric_getValue". See Metric Definition File for more details on the format of this XML file.

Parameters
[in]idAn id used by the profiler to identify this metric. This can be used in calls to Metric Plugin API functions i.e. allinea_set_metric_error_message().
[in,out]currentSampleTimeThe current time. This time is acquired from a monotonic clock which reports the time elapsed from some fixed point in the past. It is unaffected by changes in the system clock.

This is passed in from the profiler to avoid unnecessary calls to allinea_get_current_time(). If this metric is backfilled then this time is not the current time, instead it is the time at which the sample was taken and the time the sampler is now requesting a data point for.

This parameter is additionally an out parameter and may be updated with the result from a call to allinea_get_current_time() to ensure the currentSampleTime is close to the point where the metric is read. Updating currentSampleTime from any other source is undefined. In the case of a backfilled metric, currentSampleTime does not function as an out parameter and will result in an error if it is used as such. It is safe to assume that this pointer is not NULL.

Parameters
[out]outValueThe return value to be provided to the profiler. It is safe to assume that this pointer is not NULL.
Returns
0 if a metric was written to outValue successfully, a non-zero value if there was an error. In the case of an error this function should call allinea_set_metric_error_message() before returning.
Warning
This function may have been called from inside a signal handler. Implementations must not make calls that are not async-signal safe. Do not use any function that implicitly or explicitly allocates or frees memory, or uses non-reentrant functions, with the exception of the memory allocators provided by the Metric Plugin API (for example, allinea_safe_malloc() or allinea_safe_free()). Failure to observe async-signal safety can result in deadlocks, segfaults or undefined/unpredictable behaviour.
Note
Do not implement this function! Instead implement functions with the same signature but with a more appropriate function name.
int start_profiling ( plugin_id_t  plugin_id)

Called when the sampler is initialised.

An example of a function which is called when the sampler is initialised. This callback is optional and does not need to be implemented. If this function exists it can be registered as follows.

1 <source id="com.allinea.metrics.backfill_src">
2  <sharedLibrary>libbackfill1.so</sharedLibrary>
3  <functions>
4  <start>start_profiling</start>
5  </functions>
6 </source>

This function does not need to be async-signal-safe as it is not called from a signal.

Parameters
plugin_idOpaque handle for the metric plugin. Use this when making calls to allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef()
Returns
0 on success; -1 on error. A description of the error should be supplied using allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() before returning.
Examples:
backfill1.c.
int stop_profiling ( plugin_id_t  plugin_id)

Called after the sampler stops sampling.

An example of a function which is called when the sampler finishes sampling. This callback is optional and does not need to be implemented. If this function exists it can be registered as follows.

1 <source id="com.allinea.metrics.backfill_src">
2  <sharedLibrary>libbackfill1.so</sharedLibrary>
3  <functions>
4  <start>stop_profiling</start>
5  </functions>
6 </source>
Warning
This function may be called from a signal handler so must be async-signal-safe
Parameters
plugin_idOpaque handle for the metric plugin. Use this when making calls to allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef()
Returns
0 on success; -1 on error. A description of the error should be supplied using allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() before returning.
Examples:
backfill1.c.