Monitoring Condition Scripts

When adding a monitor to a tile, you might occasional find that you're unable to configure a state or threshold using the available data. Or you may want to evaluate a state based on some complex logic. In cases such as these, you can instead use a monitoring condition script.

These scripts allow you to write your own logic for returning error states to the tile editor. You can also define parameters in your scripts which you can then populate using your data stream data when configuring a tile.

Script syntax

Monitor condition scripts are written in JavaScript, and as such provide the unlimited flexibility to monitor any data in any way. The following information tells you how to define a script and details the available parameters.

Function definition

Monitor condition scripts simply consist of a single async function with the following signature. The function must be named getState and passed two parameters; params and api:

async function getState(params, api)

Return value

Your function must return an object which contains two properties; a mandatory state property and an optional scalar property.

The state property must have a value of either error, warning, success or unknown.

The scalar property is the value that caused the returned state (e.g. the value that caused the error state).

For example, a return statement could be one of the following:

• return { state: 'unknown' };
• return { state: 'success', scalar: 36.53 };
• return { state: 'error', scalar: 105 };
• return { state: 'warning' };

As a basic syntax example (see example for a more complex use case), the following code snippet returns state values depending on the current minute:

async function getState(params, api) {
    const date = new Date();
    const minute = date.getMinutes();

    if (minute < 15) {
        return 'success';
    }

    if (minute < 30) {
        return 'warning';
    }

    if (minute < 45) {
        return 'error';
    }

    return 'unknown';
}

Parameters

The params and api parameters are sued to interact with the tile data the contain the following properties and functions.

params

This object provides input data and configuration for the script.

api

This object provides helper functions for working with tile data, enabling transformation and access to formatted values.

Adding a monitor condition script

Follow these steps to add a new monitor condition script:

1. Navigate to Settings > Advanced > Scripts.
2. Click Add script.
3. Complete the following in the Add script window:
   1. Display name:
      Enter a name for your script. This helps you to identify this script in the list of your scripts.
   2. Script Type:
      Select Monitor Condition (JavaScript).
   3. Script editor:
      Enter your script. By default, you will see an example script in the editor.

4. Click Save. The script is created and added to the table.

Using a onitor conditions script

Once you've added a monitor condition script you can then select it when configuring monitoring for a tile.

1. Add or Edit the tile you want to monitor to access the tile editor.
2. Configure the tile as normal.
3. Select the Monitoring tab and do the following:
   1. Toggle Monitoring to on.
   2. Monitor type:
      Select script.
   3. Evaluate by:
      If a column is selected, the script will run multiple times for each unique value found in the selected column.
   4. Condition script:
      Select the Monitor Condition script to run from the dropdown.
   5. Config (optional):
      Specify the arguments for the params.config parameters you defined in the the script.
      For example, you could use configuration to specify thresholds for the script to use. This allows you to reuse the script for multiple tiles with different thresholds (or other configuration), and avoids having to hard-code values that may change within the script.
   6. Frequency:
      Select how often to call the script.

4. Click Save.

Example

The following example shows a script that combines two data series into a single monitored value.

Script

async function getData(params, api) {
    // Retrieve the values from the specified columns
    const metricsForA = (await api.getColumnData(params.data, 'US_errors')).map(row => row.value);
    const metricsForB = (await api.getColumnData(params.data, 'EU_errors')).map(row => row.value);

    // Compute the row-by-row sum of values from both columns
    const sum = metricsForA.map((value, index) => value + metricsForB[index]);

    // Determine the scalar as the maximum sum value
    const scalar = Math.max(...sum);
    let state = 'unknown';

    // Compare the scalar to config thresholds to determine the state
    if (scalar > params.config.errorIfMoreThan) {
        state = 'error';
    } else if (scalar > params.config.warnIfMoreThan) {
        state = 'warning';
    } else if (!Number.isNaN(scalar)) {
        state = 'success';
    }

    return { state, scalar };
}

Usage

For the script to function you must specify arguments for the parameters you defined in the script in the Config field of the Monitoring tab:

• params.config.errorIfMoreThan
• params.config.warnIfMoreThan

The config JSON you enter should look like this (the threshold values are up to you:

{
  "errorIfMoreThan": 100,
  "warnIfMoreThan": 50
}

Was this article helpful?