Metric Definition File

This topic describes the 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 must process and 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 here:

<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, ensure that metric element does not contain any whitespace and that it is chosen to minimize the risk of clashing with an existing metric name. To avoid metric name clashes, derive your metric ids from your website domain name and the name of the 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 using the command line. A metrics source library is not loaded if all metrics which it defines have been disabled.

units

The units this metric is measured in. The profiler might 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 can be specified but the profiler, might 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, only the library is enabled in one process of the node, and this process is 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

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

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 divides 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 is also multiplied by 100.0 to give a percentage value in the range 0..100.

In this situation the function specified by functionName returns a time-in-seconds value.
customData

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 must display:
- 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 color to use when displaying the metric (for example, the color of any graphs generated using this metric). This field is optional. The profiler can choose to use a color based on the type field instead of the color code specified here. Color values can 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 might 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 might 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 is referenced as in this .xml file. This id is used within the source fields of <metric>.
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 pplication to profile. Preloads are optional, and they might 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 initialized. 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().