User-defined metrics - MetricDefinition Redfish schema change proposal

["Matuszczak, Piotr" <piotr.matuszczak@intel.com>]

[-- Attachment #1: Type: text/plain, Size: 404 bytes --]

Hi,

As a result of OpenBMC telemetry WG meetings, I would like to present MetricDefinition schema change proposal to the DMTF. I would like to give you heads-up. I attach the change proposal description.

Piotr Matuszczak
---------------------------------------------------------------------
Intel Technology Poland sp. z o.o.
ul. Slowackiego 173, 80-298 Gdansk
KRS 101882
NIP 957-07-52-316


[-- Attachment #2: MetricDefinition_schema_change_proposal.md --]
[-- Type: application/octet-stream, Size: 4929 bytes --]

# MetricDefinition Redfish schema change proposal

## Background
The Redfish Telemetry Service is the API for metric management. It has the
capability of aggregating metric reports using existing Redfish sensors and
supports simple operations on metrics, like average, min, max and sum of
metrics of the same type. Most of these simple operations are single-argument,
except of sum, but it is limited to the readings of the same type sensors,
for example sum of PSU input power sensors of all PSUs present on the platform.

There are also synthesized sensors, which readings are calculated out of
metrics currently collected by the BMC. Those sensors are exposed over the
Redfish as new sensors and are supported as any other sensor. The main
disadvantage of these sensors is that they cannot be defined in runtime. They
require to be implemented in the BMC's code and any change requires BMC's
update. 

## Motivation
In order to overcome the limitation of existing sensors implementations,
user-defined sensors are introduced. The use case is to create new metric using
existing ones in runtime. In order to do this, MetricDefinition Redfish schema
will be used, but it requires some modifications to make possible configuring
math formula for readings calculation.

## Change proposal
The idea is to add 8 user-defined sensors to Redfish tree. In order to produce
readings, those sensors require to be configured by the user. Example URI for
the sensor resource is shown below. 

```
/redfish/v1/Chassis/1/Sensors/UserDefinedSensorN 
(N = 0..7)
```
The sensor configuration shall be performed in runtime using MetricDefinition
schema. In order to perform proper configuration, user has to be able to define
source metrics and also calculation formula. This will require MetricDefinition
schema extension. The example of the extended MetricDefinition is shown below.

```json
{
  "@odata.type": "#MetricDefinition.v1_0_3.MetricDefinition",
  "Id": "UserDefinedSensor0 ",
  "Name": "Definition of User-defined sensor 0",
  "MetricType": "Numeric",
  "Implementation": "Synthesized",
  "PhysicalContext": "Total PSU efficiency",
  "Units": "%",
  "SynthesisFormula": "PSU0_OUT,PSU1_OUT,+,PSU0_IN,PSU1_IN,+,/,100,*",
  "CalculationParameters": [
          {
                  "Alias": "PSU0_IN",
                  "SourceMetric": "/redfish/v1/Chassis/1/Power#/PSU/0/InputPower"
          },
          {
                  "Alias": "PSU0_OUT",
                  "SourceMetric": "/redfish/v1/Chassis/1/Power#/PSU/0/OutputPower"
          },
          {
                  "Alias": "PSU1_IN",
                  "SourceMetric": "/redfish/v1/Chassis/1/Power#/PSU/1/InputPower"
          },
          {
                  "Alias": "PSU1_OUT",
                  "SourceMetric": "/redfish/v1/Chassis/1/Power#/PSU/1/OutputPower"
          },
          {
                  "Alias": "PSU_EFF",
                  "ResultMetric": "/redfish/v1/Chassis/1/Sensors/UserDefinedSensor0"
          }
  ],
  "@odata.id": "/redfish/v1/TelemetryService/MetricDefinitions/UserDefinedSensor0 "
}
```

This is an example of total PSU efficiency user-defined metric for double-PSU
system. The original Metric Definition schema is extended by two new attributes,
the SynthesisFormula and Alias. 
* SynthesisFormula contains mathematical formula for metric calculation written
using [reverse polish notation][1] (RPN). The RPN was chosen to make the formula
easier to parse and calculate by the BMC. 
* Alias is defined for each source or result metric to ease writing the
SynthesisFormula by avoiding using sensor's URIs. 

After POSTing configuration to the proper MetricDefinition resource for given
user-defined sensor it will start to produce readings only when all required
source metrics are generating valid readings.

The table below shows the supported operators for the formula. All mathematical
operations supports integer and floating point operands and either metrics or
constants. If at least one operand is floating point the result metric also
will be floating point. Logical operations support only integer metrics.
The main use-case for them is for operations on bitmask metrics (like PSU
status bitset). The delta operator support both, integer and floating point
metrics. It calculates the delta between two subsequent metric samples.

|Operator|Meaning|Number of <br> operands| Type of <br> operation
|:-:|:-:|:-:|:-:|
| + | addition| 2 | mathematical |
| - | subtraction | 2 | mathematical |
| * | multiplication | 2 | mathematical |
| / | division | 2 | mathematical |
| < | shift left | 2 | logical |
| > | shift right | 2 | logical |
| & | bitwise AND | 2 | logical |
| \| | bitwise OR | 2 | logical |
| ~ | bitwise NOT | 1 | logical |
| $ | Delta | 1 | mathematical |

[1]: https://en.wikipedia.org/wiki/Reverse_Polish_notation