Arm MAP Metric Plugin Interface
Metric Plugin Interface for MAP
Arm Performance Reports Integration

Introduction

To integrate one or more metric plugins into Arm Performance Reports, provide a small 'partial report' file that describes the additions to be made to a Performance Report. This report should display 'report metrics' which are obtained by combining the metric-specified values sampled for a metric. It is possible to select which values from a metric (min, max, mean or sum) to be used and how to accumulate them (min, max or mean).

Default definition file location

This custom partial report content can be defined in one or multiple custom report definition files, that have to be placed under the following folder structure in the default configuration path: ~/.allinea/perf-report/reports/

When multiple files are found in the directory, all are loaded and used during report generation.

To redefine the default configuration folder, use the ALLINEA_CONFIG_DIR environment variable.

Note: The default configuration folders sub-folder structure must be the same in order to use this feature (for example, $ALLINEA_CONFIG_DIR/perf-report/reports/).

Custom definition file location

The location of the custom partial report definition file(s) can be overriden using ALLINEA_PARTIAL_REPORT_SOURCE environment variable, which can either point to a single XML file or a folder containing XML files. When a folder is specified, the sub-folders are not searched for files but all XML files from that level will be loaded in ascending alphabetical order.

Partial report definition file

General layout of the file is the following: first define the report metrics that need to be used in the report, then define the layout of the subsections that are visible in the report.

An example partial report definition file:

<partialReport name="com.allinea.myReport"
xmlns="http://www.allinea.com/2016/AllineaReports">
<reportMetrics>
<!-- multiple <reportMetric> elements can be defined -->
<!-- source attribute must be set to "metric" -->
<reportMetric id="com.allinea.metrics.sample.average"
tooltip="Metric tooltip."
displayName="Average of custom interrupt metric"
units="/s"
colour="hsl(19, 70, 71)"
source="metric">
<!-- metricRef: reference to an entry in metricdefinitions element -->
<!-- sampleValue: data value from each sample to take: min, max, mean or sum across processes -->
<!-- aggregation: how to aggregate per-sample values into a single value: min, max, mean across time -->
<sourceDetails metricRef="com.allinea.metrics.sample.interrupts"
sampleValue="mean"
aggregation="mean"/>
</reportMetric>
</reportMetrics>
<subsections>
<!-- multiple <subsection> elements can be defined -->
<subsection id="my_metrics"
heading="My metrics"
colour="hsl(23, 83, 59)">
<text>Section one:</text>
<!-- multiple <entry> elements can be defined -->
<entry reportMetric="com.allinea.metrics.sample.average"
group="interruptGroup" />
</subsection>
</subsections>
</partialReport>

<partialReport>

<partialReport name="com.allinea.myReport"
xmlns="http://www.allinea.com/2016/AllineaReports">
</partialReport>
name:
A name that uniquely identifies this report. The name is used to distinguish between different kind of reports. See Reserved Names/IDs and Restrictions for reserved names.
xmlns:
The xmlns="http://www.allinea.com/2016/AllineaReports" attribute must be included in the <partialReport> element.

<reportMetrics>

Container for one or more <reportMetric> elements.

<reportMetric>

<reportMetric id="com.allinea.metrics.sample.average" displayName="Average of custom interrupt metric" tooltip="Metric tooltip." units="/s" colour="hsl(19, 70, 71)"
source="metric">
<sourceDetails metricRef="com.allinea.metrics.sample.interrupts" sampleValue="mean" aggregation="mean"/>
</reportMetric>

Each <reportMetric> element describes a single metric that is stored as a double value.

id:
A unique identifier for this metric. This will be used to reference this metric in <entry> element(s). Ids with dots in their value should not be substrings of each other. For example, com.allinea.metrics.sample is a substring of com.allinea.metrics.sample.average and therefore not allowed. See Reserved Names/IDs and Restrictions for reserved names.
displayName:
The name for this metric, as it will appear in the report.
tooltip (optional):
A tooltip to be displayed when hovering over the metric name.
units:
The units this metric is measured in, as it will appear in the report. Units are auto-scaled with SI (G, M, k) and IEC (Gi, Mi, ki) prefixes, but no negative exponent scaling is performed. You should scale custom metrics and select custom units accordingly.
colour (optional):
The colour to be used for this metric when it is named in the report. Colour is also used for comparison bars showing the relative value of this metric. See Colour codes.
source:
Source type of this metric, must be set to metric.

<sourceDetails>

<sourceDetails metricRef="com.allinea.metrics.sample.interrupts" sampleValue="mean" aggregation="mean"/>

Describes the details of the source metric used in this report element.

metricRef
Reference to an existing metric, can be either an Arm or a user defined (custom) metric.
sampleValue
Which sample value of the referenced source metric to be used (options: min/max/mean).
aggregation
How aggregated samples are aggregated (options: min/max/mean).

<subsections>

Container for one or more <subsection> elements.

<subsection>

<subsection id="my_metrics"
heading="My metrics"
colour="hsl(23, 83, 59)">
<!-- can add a <text> element with further description -->
<!-- multiple <entry> elements can be defined -->
</subsection>

Describes the layout of the data to be displayed.

id:
A unique identifier for this subsection.
heading:
The display name for this subsection.
colour (optional):
The colour to use for the heading text. See Colour codes.

<text>

<text>Section one:</text>

Short static description of this subsection.

<entry>

<entry reportMetric="com.allinea.metrics.sample.average"
group="interruptGroup" />

Describes one of the metrics to be listed in the subsections of the report.

reportMetric:
Referenced report metric that is to be displayed.
group (optional):
The optional group attribute is used to determine how to scale comparison bars that indicate the relative size of two or more metric values. If two <entry> elements have the same value for their group attribute, they are considered comparable and have comparison bars drawn using the same scale.

Colour codes

Colours may be specified in one of the following forms:

  • #RGB (each of R, G, and B is a single hex digit)
  • #RRGGBB
  • #RRRGGGBBB
  • #RRRRGGGGBBBB
  • rgb(X,Y,Z) (each of X, Y, and Z is a decimal value in the range 0-255)
  • hsv(H,S,V) (H in the range 0-359, S, and V in the range 0-100)
  • hsl(H,S,L) (H in the range 0-359, S, and L in the range 0-100)
  • A name from the list of colours defined in the list of SVG colour keyword names provided by the World Wide Web Consortium: https://www.w3.org/TR/SVG/types.html#ColorKeywords

Reserved Names/IDs and Restrictions

All names and IDs starting with allinea. or com.allinea. are reserved and can not be used in the partial report definition file. Instead, for example use your reversed Internet domain name as prefix.

IDs must be a valid XML NCName (see https://www.w3.org/TR/xmlschema-2/#NCName) - it cannot contain symbols (except '.', '_' and '-'). Note: IDs cannot begin with '.' or '_'.

HTML Markup

Most text in the partial report definition XML file that will be inserted directly into the generated report can contain a limited subset of HTML markup. Supported elements include headings, ordered and unordered lists, span, div, p, a b, i, img etc.