Arm MAP Metric Plugin Interface
Metric Plugin Interface for MAP
Metric Definition File

To add metric libraries that implement the Metric Plugin Template and make calls to the Metric Plugin API to compatible profilers, use a metric definition file.

This is a short xml file that defines the location of a metric plugin library and lists both the metrics that library can provide, and how the profiler should process & display the metric data returned by that library.

A metric definition file uses the format:

<metricdefinition version="1">
<!-- 'metric' element(s) defining the metrics provided by the library -->
<!-- 'metricGroup' element(s) describing how the metrics should be
grouped when displayed by a profiler -->
<!-- 'source' element(s) specifying the location of the metrics library
the profiler should load and, optionally, a list of libraries to
preload into the profiled application -->
</metricdefinition>

See custom1.xml for a complete metric definition file. The elements are described in detail below:

<metric>

<metric id="com.allinea.metrics.myplugin.mymetric1">
<enabled>[always|default_yes|default_no|never]</enabled>
<units>%</units>
<dataType>[uint64_t|double]</dataType>
<domain>time</domain>
<onePerNode>[false|true]</onePerNode>
<source ref="com.allinea.metrics.myplugin_src" functionName="mymetric1" customData="mydata"/>
<display>
<description>Human readable description</description>
<displayName>Human readable display name</displayName>
<type>instructions</type>
<colour>green</colour>
</display>
</metric>

Each <metric> element describes a single metric that is provided by a metric plugin library. The id attribute of the opening <metric> element is the identifier used by this definition file and the profiler to uniquely identify this metric. To avoid confusion, this should not contain any whitespace and should be chosen to minimize the risk of clashing with an existing metric name. To avoid this, derive your metric ids from your website domain name and the name of plugin library, for example com.allinea.metrics.myplugin.mymetric1

enabled:
Specifies whether the metric is enabled or not. Options are always, never, default_yes, default_no enabled. This allows you to explicitly enable or disable the metrics listed as default_no or default_yes enabled via the command line. A metrics source library will not be loaded if all metrics which it defines have been disabled.
units:
The units this metric is measured in. The profiler may automatically rescale the units to better display large numbers, for example, convert B to KB). Possible values include % (percentage in the range 0..100), B (bytes), B/s (bytes per second), calls/s (calls per second), /s (per second), ns (nanoseconds), J (joule) and W (watts, joules per second). Other units may be specified but the profiler, may not know how to rescale for particularly large or small numbers.
dataType:
The datatype used to represent this metric. Possible values are uint64_t (exact integer) and double (floating point).
domain:
The domain in which sampling occurs. The only supported domain is time.
onePerNode
If false, all processes report this metric. If true, only one process on each node (machine) calculates and returns this metric. Use true when the metric is a machine-level metric that can not be attributed to an individual process. The default value (if this element is omitted) is false.
If all the metrics of the library have <onePerNode> set to true, the library only is enabled in one process of the node, and this process will be the only one to call the allinea_plugin_initialize and allinea_plugin_cleanup functions.
backfill
If true, the metric getter is called once for each sample when the user application is ending (for example, in MPI_Finalize or atexit) or the sampling has stopped after a timeout. If false, or the tag is not present, then the metric getter collects data at sample time. For more information on backfilling, see the examples backfill1.c and backfill1.xml
source:
  • ref is the id of the <source> element detailing the metric plugin library that contains that function. The function in functionName must have the appropriate signature for a metric getter, see mymetric_getIntValue() as an example.
  • functionName is the name of the function to call to obtain a value for this metric.
  • divideBySampleTime: (Not used in example) If true, the metric getter function returns the difference in the measured value since the last sample. The profiler should divide the returned value by the time elapsed since the last sample to get the true value. If false, the value returned by the getter function is left unaltered.

    As a special case, if units is % (percentage) and divideBySampleTime is true the result will also be multiplied by 100.0 to give a percentage value in the range 0..100 (in this situation the function specified by functionName should return a time-in-seconds value).

  • customData is a custom data string associated with this metric id, which can be extracted in the metric plugin library with a call to allinea_get_custom_data.
display:
Options describing how this metric should be presented:
  • description A human-readable description of this metric, suitable for tooltips or short summary text.
  • displayName The human-readable display name for this metric
  • type Identifies the broad category this metric falls under. Currently supported values are cpu_time, energy, instructions, io, memory, mpi, and other.
  • colour A colour to use when displaying the metric (for example, the colour of any graphs generated using this metric). This field is optional - the profiler may choose to use a colour based on the type field instead of the colour code specified here. Colour values may be:
    • an RGB hex code of the form #RGB, #RRGGBB, #RRRGGGBBB or #RRRRGGGGBBBB (each of R, G, and B is a single hex digit).
    • an SVG color keyword, for example, green.
  • rel Specifies related metrics. The only supported related metric type is "integral". This type may be used to specify another metric which is an integral of the metric being defined, for example rapl_energy is an integral of rapl_power:
    <rel type="integral" name="rapl_energy"/>

<metricGroup>

<metricGroup id="foo">
<displayName>Foo Metrics</displayName>
<description>All metrics relating to foo.</description>
<metric ref="com.allinea.metrics.myplugin.mymetric1"/>
<metric ref="com.allinea.metrics.myplugin.mymetric2"/>
<metric ref="com.allinea.metrics.myplugin.mymetric3"/>
</metricGroup>

Each metricGroup element describes a collection of metrics to be grouped together. The UI of the profiler may provide actions that apply to all metrics of a group (such as, show or hide all metrics of a group). Metric groups are for display purposes only and do not affect the gathering of metrics.

displayName:
A human readable name for this metric group.
description:
A human-readable description of this metric group, suitable for tooltips or some short summary text.
metric:
One or more elements each referencing a <metric> element elsewhere in this .xml file.

<source>

Each <source> element represents a metric plugin library that is available for loading. The specific metrics in that library are listed as <metric> elements above.

<source id="com.allinea.metrics.myplugin_src">
<sharedLibrary>lib-myplugin.so</sharedLibrary>
<preload>lib-mywrapper1.so</preload>
<preload>lib-mywrapper2.so</preload>
<functions>
<start>user_application_start</start>
<stop>sampling_stop</stop>
</functions>
</source>
id:
The id this library will be referenced as in this .xml file. This id is used within the source fields of <metric> elements.
sharedLibrary:
The library implementing the Metric Plugin Template. This must be located in a directory that is checked by the profiler. To resolve this library name, see the documentation of the profiler to determine which directories are searched.
preload:
A list of shared libraries to be preloaded into the application to profile. Preloads are optional, and they may be used to wrap function calls from the profiled application into other shared libraries. The sharedLibrary preloads have to be located in a directory checked by the profiler.
start:
The name of the function to call when the sampler is initialised. This function is optional but must have the same signature as start_profiling().
stop:
The name of the function to call when the sampler has ceased taking samples. This function is optional but must have the same signature as stop_profiling().