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