Documentation.

Metrics.

Metrics are the elements of a subject you want to monitor. All metric types - ingested, calculated and simulated - have several visualization and visibility options:

Attribute Description
Unit Provide the unit of measurement. E.g. hPa, Celcius or meters.
Decimal precision Determine how many figures are shown after the comma
Y-axis lower bound Determine the lower bound of the graph. Leaving empty will result in a lower bound based on the data.
Y-axis upper bound Determine the upper bound of the graph. Leaving empty will result in a upper bound based on the data.
Stale time (minutes) Raise the stale time well above the expected frequency interval of the measurements. The graph will show gaps when data is not received within the stale time.
E.g. Set the stale time to two minutes, when it is expected to get a measurement every minute.
Hide Choose whether you want to see the metric on the subject dashboard

Ingested metric

An ingested metric receives data from a device, sensor or other external system. Example: a sensor that is sending values for both temperature and humidity.

Attribute Description
Name Give the ingested metric a descriptive name so you can easily recognize and find it.
External ID Provide the ID the metric has in your own systems. In this way you can easily map metric to the ID naming conventions they relate to in your own systems. This external ID is also used to construct the default ingestion IDs you have to provide when sending measurements for ingested metrics.

Calculated metric

A calculated metric can be computed from the values of one or more metrics and numeric properties within a subject. A simple example will be an electrical station for which you want to compute the wattage by multiplying voltage with amperage (this is made visible in the examples).

The main elements of a calculation are the name (1) together with the arguments (2) that can be used in the calculation (3).

Calculated metric edit

Arguments

In a calculation metrics and numeric properties within a subject type can be used. These metrics and properties are referred to as the arguments of the calculation.

Attribute Description
Source Either a metric or a property with a numeric value present on the subject type
Alias A name without spaces that can be used to refer to the argument in the computation
Max age For metric sources this specifies how long ago a measurement may have been received to be used for the calculation

For metrics configured as argument it is possible to use its value and/or date in the computation. For example if we add a Wattage metric as argument with alias wattage we can use its value with wattage.value and its date in milliseconds with wattage.date. For properties configured as argument it is possible to use its value. For example if we add a property Height with alias height we can use its value with height.value.

Max age explained

A calculation is always triggered when a measurement is received on a metric that is used in the calculation. Next, measurements of the other metrics are retrieved based on the max age that is configured. Here are some examples:

Max age metric 1 Max age metric 2 Results
0 seconds 0 seconds The calculation will only proceed when both metrics have a measurement with the same timestamp (in milliseconds)
0 seconds empty Measurement for metric 1 received, the last known measurement of metric 2 will be used for the calculation. Measurement for metric 2 received, the calculation will only proceed when there is a measurement of metric 1 with the same timestamp (in milliseconds)
empty 60 seconds Measurement for metric 1 received, the calculation will proceed when there is measurement of metric 2 which is not older than 60 seconds. Measurement for metric 2 received, the last known measurement of metric 1 will be used for the calculation

Calculation

The calculation is defined using the editor in a user-friendly language. The language allows you to:

At last but not least, formulating a calculation is getting more convenient when you use the editor features and watch the examples.

Define variables

For your convenience and readability of your calculation it is possible to split your calculation into smaller calculations. Each of the smaller calculations may be saved in a variable definition. An example of this is wattage = voltage.value * amperage.value in the example at the start of this section. This allows referring to the result of the computation voltage.value * amperage.value via the name wattage.

Arithmetic operations

All basic arithmetic operations can be applied to values in your calculation:

Operation Symbol Example Comment
Addition + 5 + 7 -
Subtraction - 10 - 5 -
Multiplication * 3 * 9 -
Division / 10 / 2 Division by 0 will produce no result
Parenthesis ( ) (5 + 7) * 8 Here 5 + 7 takes precedence over multiplication by 8

Multiplication and division take precedence over addition and subtraction, as per the standard arithmetic rules. Any (decimal) number values, variable definitions, loaded values or input argument values can be used in arithmetic. Operations can also be chained. Some examples:

load sum with default 0
a = voltage.value * 5.5
b = a - 7 + 8 / 2
c = sum + b
save c as sum
d = (c + 10) * 5
output d
Functions

Many default computations are available as functions. Functions can be used anywhere in your computation where a numeric value is expected, and can take as input any literal value, input argument value, loaded value or arithmetic. For example: compute and output the maximum value of a metric argument with alias inputMetric so far using the max function:

load maxValue
newMaxValue = max(maxValue, inputMetric.value)
save newMaxValue as maxValue
output newMaxValue

max(value1,value2)

Computes the maximum value of two number values.

Parameter Description
value1 First value to compare
value2 Second value to compare

min(value1,value2)

Computes the minimum value of two number values.

Parameter Description
value1 First value to compare
value2 Second value to compare

sin(degrees)

Computes the sine of the provided number of degrees.

Parameter Description
degrees Input in degrees

cos(degrees)

Computes the cosine of the provided number of degrees.

Parameter Description
degrees Input in degrees

tan(degrees)

Computes the tangent of the provided number of degrees.

Parameter Description
degrees Input in degrees

round(value,precision)

Rounds decimal numbers to a specified number of decimals. Precision rounded down to closest integer value.

Parameter Description
value Value to round
precision Number of decimals to round to (max 8). Decimals precision values are rounded down to nearest integer.

floor(value)

Rounds decimal numbers down to the closest integer value.

Parameter Description
value Value to round

ceil(value)

Rounds decimal numbers down to the closest integer value.

Parameter Description
value Value to round

random(lower,upper)

Generates a random decimal number from a continuously uniform distribution between provided upper and lower bounds.

Parameter Description
lower Lower bound for random number (inclusive)
upper Upper bound for random number (exclusive)

pow(value,power)

Computes the power of a number value.

Parameter Description
value Input value to compute power for
power Power value. Decimal power values are rounded down to the closest integer value.

sqrt(value)

Computes the square root of a number value.

Parameter Description
value Input value to compute square root for

pi()

Provides the value of Pi with eight decimals of precision.

now()

Provides the current time in milliseconds since Unix Epoch.

abs(value)

Computes the absolute value of a number value.

Parameter Description
value Input value to compute absolute value for

remainder(dividend,divisor)

Computes the remainder of a division. For example, the remainder of 9 / 2.5 is 1.5. The remainder always takes the sign of the dividend.

Parameter Description
dividend Dividend of the division
divisor Divisor of the division

distanceBetween(latitudeFrom,longitudeFrom,latitudeTo,longitudeTo)

Computes the Geodetic (across the Earth’s surface) distance between two points using the WGS84 coordinate reference system.

Parameter Description
latitudeFrom From position latitude in degrees
longitudeFrom From position longitude in degrees
latitudeTo To position latitude in degrees
longitudeTo To position latitude in degrees

now()

Provides the current time in milliseconds since Unix Epoch.

distanceBetweenXY(xFrom,yFrom,xTo,yTo)

Computes the Euclidean (straight) distance between two 2D points. Distance is in the same unit as provided coordinates.

Parameter Description
xFrom From position x coordinate
yFrom From position y coordinate
xTo To position x coordinate
yTo To position y coordinate

distanceBetweenXYZ(xFrom,yFrom,zFrom,xTo,yTo,zTo)

Computes the Euclidean (straight) distance between two 3D points. Distance is in the same unit as provided coordinates.

Parameter Description
xFrom From position x coordinate
yFrom From position y coordinate
zFrom From position z coordinate
xTo To position x coordinate
yTo To position y coordinate
zTo To position z coordinate

Save and load values

It is possible to save and load values between consecutive evaluations of the calculation. A numeric value can be saved at the end of a calculation, so that it can be loaded the next time the calculation is evaluated. A maximum of 10 values can be saved. For example: we want to compare the value of a metric to its previous value.

load previousValue
difference = bitcoin.value - previousValue
save bitcoin.value as previousValue
output difference

Values must be loaded at the beginning of a calculation with a name that that is later used to save the value. See load previousValue will create a variable with name previousValue. If a variable is loaded, a value must be saved in it at some point during the calculation. See save bitcoin.value as previousValue which saves the current bitcoin metric value in previousValue to be used by the next evaluation of the calculation.

It is possible to use the value of a loaded variable to update its own value. For example when we are keeping a sum:

load bitcoinSum with default 0
newSum = bitcoinSum + bitcoin.value
save newSum as bitcoinSum
output newSum

In this case a default must be provided when loading the variable, see load valueSum with default 0. This default value is used when the load variable does not yet have a value, if this default was not present it would never be possible to set a value initially.

Output

Each calculation must specify exactly one output value at the end of the calculation as follows: output <value>. In this case <value> can be any (decimal) number value, arithmetic, variable definition, loaded value or argument value.

Important to keep in mind:
  • A calculated metric is triggered when a measurement of one of the arguments is received.
  • A calculation will only take place when all variables within the calculation are present.
  • Above condition holds for each saved value and output independently. So a loaded value could be saved in a previous evaluation while no output was generated.
Editor features

The editor has some smart features which makes it easy to use, but these features are not visible from the outside. The features are listed in the table and showed in the video below the table.

Feature Action Description
Extra info hover Use the mouse to hoover over the elements in the editor to see extra information.
Option list ctrl + space Get to see the list options you can select in the current context.
Option description ctrl + space Hit ctrl + space a second time to see the description of the option.
Commenting // or /* -> */ Put // at the start of a line to write a single-line comment. Alternatively start a multi-line comment with /* and end it with */
Red underline N/A A (part of) the calculation has a red underline when the editor detects a possible mistake. Hover the red underline for more details and suggestions.
Calculated metric edit

Examples

This section show some examples to make calculated metrics concrete and explain the settings.

Wattage calculation

The wattage will only be calculated when when voltage and amperage are received with the same timestamp. This is due to zero seconds max age setting for both arguments.

Calculated metric example 1


Heat index

The heat index (Dutch: gevoelstemperatuur) will be calculated with the last known temperature measurement when the humidity measurement is received and with a humidity measurement not older than 10 seconds when a temperature measurement is received.

Calculated metric example 2

Simulated metric

An simulated metric generates data based on the configuration. Example: a two hour sinus.

Attribute Description
Name Give the simulated metric a descriptive name so you can easily recognize and find it.
Simulation type Choose between a random walk and sinus two hours.
Measurement interval Choose with which frequency measurements are generated.
Value lower bound Determine what the lowest value will be for the measurements that are generated.
Value upper bound Determine what the highest value will be for the measurements that are generated.