Computed measurement

This page describes computed measurement in detail.

The first thing to do when designing a computed measurement is to decide what are the inputs and what to output. A computed measurement can specify multiple measurements as input. Metrics and tags in those measurement will then be available to the function that is responsible for generating the output.

  ... what are valid inputs ...
  ... what is a valid output ...

Implementation

 ... describe what functions the developer must override, and what is the expected behaviour of those functions ...
 ... Junhao feedback that it is unclear that you must output a valid measurement. he thought he has to always output something, like NULL during initial invocation ...

Testing

 ... how to test ...
 ... limitations of the test environment ...

Execution

 ... describe when the compute function will be run. ...
 ... describe caveats when using multiple measurements - eg. measurement 1 and measurement 2 can come in at different times, and compute will be called twice ...

Examples

Example 1: Temperature Scale Conversion

This example shows a simple usage of computed measurement.

Imagine you have a temperature sensor that sends raw temperature values in degrees Farenheit (℉) and you want to show the temperature in degrees Celsius (°C) instead. This is the temperature measurement from the temperature sensor that you have as input:

 {
   "tm_source": xxxxxxxxxx,
   "site_id" xxxxxxxx,
   "tag1": "xxxxxxxx",
   "tag2": "xxxxxxxx",
   "temperatureF": xxxxxxxxx
 }

And this is the computed measurement that you want to output:

 {
   "tm_source": xxxxxxxxxx,
   "site_id" xxxxxxxx,
   "tag1": "xxxxxxxx",
   "tag2": "xxxxxxxx",
   "temperatureC": xxxxxxxxx
 }

You can use the following script to perform the temperature metric conversion:

 /**
  * @name: init
  * @description: Perform one-time initialization of your script
  * param {string}
  **/
 async function init() {
   // No initialization tasks required for this simple example
 } 
 
 /**
  * @name: compute
  * @description: Perform computation on watching measurements. This function is called when new measurements arrive
  * @param {string} measurement - The source measurement name
  * @param {Array.<object>} - Array of measurement data
  **/
 function compute(measurement, data) {    
   // Loop through the array of incoming measurements,
   // and convert 'temperatureF' to 'temperatureC'
   for (let i = 0; i < data.length; i++) {
     const inputMeasurement = data[i];
     const temperatureF = inputMeasurement.temperatureF;
  
     // Calculate the temperature in C
     const temperatureC = (temperatureF − 32) * 5/9; 
  
     const outputMeasurement = {
       tm_source: inputMeasurement.tm_source,
       site_id: inputMeasurement.site_id,
       tag1: inputMeasurement.tag1,
       tag2: inputMeasurement.tag2,
       temperatureC: temperatureC,
     };  
   
     // Output computed measurement
     output(outputMeasurement);
   }
 }
 
 /**
  * @function output 
  * @description: User-invoked function to output a computed measurement
  * @param {String} outputMeasurment - Output measurement name
  * @param {Object} outputData - Object containing output metrics (required tags, optional tags, measurement metrics)
  * @param {string} outputData.tm_source - Timestamp (Same as input measurement)
  * @param {string} outputData.site_id - Site Id (Same as input measurement)
  * @param {string} outputData.tag1  - Tag1 (Same as input measurement)
  * @param {number} outputData.tag2 - Tag2 (Same as input measurement)
  * @param {boolean} outputData.temperatureC - Calculated temperature in C
 **/

Example 2

 ... give a more complex example ...