Metrics Tutorial

Metrics are system specific data that can change over time.  Contrast this with static data which always stay the same, each metric is a javascript function which executes on every server update.  The function returns a promise allowing for asynchronous programming.  In practical terms, this means you can execute a custom linux script, get the result, and then pass it as the value of the metric.  This is a great way to fully customize the server data that is being sent to the cluster.

The metric function

A metric function looks like this. This function returns a random number on each iteration

function (input = {}) { 
  return new Promise ((resolve, reject) => {
    return resolve (Math.random ())
  });
}

The first line is the function declaration

function (input = {}) { 

Then we return a promise which will resolve sometime in the future

return new Promise ((resolve, reject) => {
    return resolve (Math.random ())
  });

Don’t forget the closing bracket!

}

This function has full access to the nodejs environment, which means it can pull in any node module available to it. While nodejs is a great environment to work in (FastX is built on it!), most integrators will probably want to simply execute a script written in a language that they are more familiar with. Let’s see how we can do that

The input object

Currently the input object is empty {}

The metric function calling an outside script

function metric (input = {}) {
   let file = '/usr/bin/echo'; //path of script to exec
   let args = [ (1 + Math.random ()*10) ]; //array of arguments to pass to the script
   const execFile = require ('child_process').execFile; //require the exec function from a node module
   return new Promise ((resolve, reject) => {  //create a promise to be resolved later
      execFile ( file, args, (err, stdout, stderr) => { //execute the command 
          if (err) return reject (err); //fail (reject) if there is an error
          if (stderr.length) return reject (new Error (stderr)); //fail if there is standard error
          console.log ('e',stdout)
          return resolve (Number.parseInt (stdout, 10)); //return the random number as an INT
      });
   });
}

This example makes use of the  child_process node module.  You can adapt this function by modifying the file and the args variables to execute your own custom script that will give the result you need.

Note: stderr and stdout always return strings.  Here are some helper functions you may want to know about to get the output in a easier to use format

  • Number.parseInt (string, radix) — parses a string argument and returns an integer of the specified radix
  • Number.parseFloat (string) — parses a string argument and returns a floating point number
  • JSON.parse (string) — parses a JSON string, constructing the JavaScript value or object described by the string.  You can also use this function to convert string “true” and “false” to boolean true/false

Testing your function

After you create the function the best way to test is to call it.  Copy your function to a test.js file.

Add the line to the bottom of the file

metric ().then (console.log,console.log);

This line will call the function and log either the result, or the error