![]() |
Arm MAP Metric Plugin Interface
Metric Plugin Interface for MAP
|
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:
See custom1.xml for a complete metric definition file. The elements are described in detail below:
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
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.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.uint64_t
(exact integer) and double
(floating point).time
.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
.<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.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.xmlref
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.description
A human-readable description of this metric, suitable for tooltips or short summary text.displayName
The human-readable display name for this metrictype
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: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:
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.
.xml file.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.
.xml file. This id is used within the source
fields of <metric>
elements. sharedLibrary
preloads have to be located in a directory checked by the profiler.