State change conditions

This section allows you to configure state change conditions for entities.

This section has the following controls:

The button allows you to add comments, that will be displayed in the State history section of the entity and sent in notifications.
The Apply button applies changes to the state change conditions. The Cancel button cancels them.

The Apply to class button sets object’s conditions as the default conditions for the class of the object.

New default conditions do not override previously modified conditions of manually changed objects since they set to be "unique".

List of objects whose state change conditions will not be overridden is displayed in the following popup:

The Derive from class button applies default conditions for that class to the current object.
By clicking the button at the header, the graphic condition constructor can be switched to the text mode:

Conditions settings

The State change conditions section contains a kit of records. Each record consists of:

Condition:
- type (compare/splash/predict/data expiration);
- data source is the metric name from the Data table of the current or external object;
- comparison operator from the dropdown list, for instance, = or matches;
- value to compare with.
Action - transition the state to the selected one when the condition is met.

The types Splash and Predict are available only when the analytics module is activated.

A condition with the Data expiration type is met, should any data do not come to the system during the probe period. By default, in that case the object’s state transits to the NO DATA one. The rest of the fields are absent for conditions of this type.

Mathematical comparison operators are used for numeric values; textual operators are used for numeric and text values, case-insensitive.

The operators = and ≠ can also be used with text values, case-sensitive.

It is possible to use regular expressions with textual comparison operators such as matches.

Conditions construction

Any condition can be composed of several subconditions joined by the AND logic operator. In this case subconditions are joined with the brace on the right:

You can find out more about the data selection algorithm for multiple conditions in the glossary:state-conditions.adoc#data-select-algorithm section.

The buttons and to the right of value add and delete the condition respectively.

A condition can be empty. An empty condition is always met.

The buttons and to the right of action add and delete the entire system of conditions respectively.

The button activates manual input of data source. Manual input allows to:

type in the metric name if it is not in the dropdown list,
use masks in metric names, for example *pfree*,
specify the external metric,
use mathematical formulas.

State change with errors

If a probe has been finished with an error, the text of the error is displayed in the data table in the Sensor error metric. In that case the following logic of state changing works:

if state change conditions were not set for the object, or there is no condition that matches the Sensor error metric, the object’s state changes to the ALARM.
if a condition, which was set using the Sensor error metric, is met, the object’s state transits to the state of the condition.

If there is an error in state change conditions, the object changes its state to ALARM when data comes. There will be the Incorrect state condition reason in state history:

Additional operators

The button to the right of the value field allows to add additional operators:

duration, which defines how long the condition must be satisfied continuously to change the object state:
period, which allows to specify the time period when the configured condition is checked:

flapping, which allows to specify the required number of executions of the configured condition during the selected time interval:

Flappings allow to detect short-term self-healing incidents, but they cannot identify a stable emergency. It is recommended to use the flapping functionality in combination with the duration functionality lest any alarm is lost.

The image below shows state change conditions for a device that sends an SNMP Trap about an interface state changing. If the device sends the sequence "Down - Up (or any other than Down) - Down - Up (or any other than Down) - Down" in 10 seconds, then the first condition will be met and the object will go into the OVERLOADED state.

If the device sends the string "Down" and it lasts 10 seconds, then the second condition will be met and the object will go into the ALARM state.

If the device sends the string "Up" and it lasts 10 seconds, then the last condition will be met and the object will go into the WORKING state.

It is possible to set a condition without specifying a metric and its value. For example, on weekends the state is WORKING:

Actions on data expiration

By default, when there are no data in the system by the end of the probe period, the object’s state transits to the NO DATA one,

If data expiration of completed probe is not a cause for the alarm, and the object is not needed to be transit to the NO DATA state, it is possible to use a condition of the Data expiration type.

As the action it is possible to set Do not change state, or select a state without specified alarm severity from the list.

For example, if the object gets data about errors (if there are no errors - there is no incoming data sets), the following changes object state to the WORKING when the data expires:

Metrics from external objects

It is possible to use metrics from external objects with setting up state change conditions.

To use external metrics, you need to have access to the objects you’re pulling metrics from.

To use external metrics, specify the object ID and the name of the metric to be used after the colon with the manual metrics input .

For example, to use the packetsTransmitted metric from the object with the ID = 634020c368413b26524a3424, input the following string:

634020c368413b26524a3424:packetsTransmitted

The following code example shows raw input for external metrics:

[
  {
    "condition": {
      "634020c368413b26524a3424:packetsTransmitted": {
        "_eq": "4"
      }
    },
    "state": 3,
    "description": "",
    "externalRefs": [
      {
        "id": "634020c368413b26524a3424",
        "metric": "packetsTransmitted"
      }
    ]
  }
]

This functionality can also be used in the formula editor.

For example, to use external metrics packetsTransmitted and packetsReceived of objects with IDs 634020c368413b26524a3424 and 634020d668413b26524a342b respectively, use the following string:

{{634020c368413b26524a3424:packetsTransmitted}} - {{634020d668413b26524a342b:packetsReceived}}

The following code example shows raw input for formulas with external metrics:

[
  {
    "condition": {
      "_formula": {
        "definition": "{{634020c368413b26524a3424:packetsTransmitted}} - {{634020d668413b26524a342b:packetsReceived}}",
        "value": {
          "_eq": "0"
        }
      }
    },
    "state": 3,
    "description": "",
    "externalRefs": [
      {
        "id": "634020c368413b26524a3424",
        "metric": "packetsTransmitted"
      },
      {
        "id": "634020d668413b26524a342b",
        "metric": "packetsReceived"
      }
    ]
  },
  {
    "condition": {},
    "state": 5,
    "description": ""
  }
]

Mathematical operations

To create more complex conditions based on mathematical operations, it is possible to use the formula editor.

Formulas input

To use formulas:

Switch to the manual input mode .
Enter the metric name in the Data source field or select it in the filtered list of options. The name of each metric must be written in braces as follow: {{metric_name}}.
Input the formula using mathematical symbols, constants and braces.

For example, the difference between the maximal round-trip time and of minimal round-trip time: {{roundTripMaximum}} - {{roundTripMinimal}}.

The result of calculations will automatically be displayed over the entered mathematical operation.

Available operations, operators and functions

Operations

Operation	Description
!	Factorial
^	Exponentiation
*	Multiplication
/	Division
%	Remainder of division
+	Addition
-	Subtraction
\|\|	Concatenation
==	Equal
!=	Not equal
>=	Greater or equal
<=	Less or equal
>	Greater
<	Less
and	Logical AND
or	Logical OR
not	Logical NOT

Operation

Description

Factorial

Exponentiation

Multiplication

Division

Remainder of division

Addition

Subtraction

Concatenation

Equal

Not equal

Greater or equal

Less or equal

Greater

Less

and

Logical AND

Logical OR

not

Logical NOT

Operators

Operator	Description
x!	Factorial (x * (x-1) * (x-2) * … * 2 * 1). gamma(x + 1) for non-integers
abs x	The absolute value of x
ceil x	Round to the next integer
floor x	Round to the previous integer
length x	String length of x
round x	Round to the nearest integer
sqrt x	Square root of x
trunc x	Remove the fractional part of x
exp x	e^x (exponential/antilogarithm function with base e)
ln x or log x	Natural logarithm of x
log10 x	Base-10 logarithm of x
acos x	Arc cosine of x (in radians)
acosh x	Hyperbolic arc cosine of x (in radians)
asin x	Arc sine of x (in radians)
asinh x	Hyperbolic arc sine of x (in radians)
atan x	Arc tangent of x (in radians)
atanh x	Hyperbolic arc tangent of x (in radians)
cos x	Cosine of x (in radians)
cosh x	Hyperbolic cosine of x (in radians)
sin x	Sine of x (in radians)
sinh x	Hyperbolic sine of x (x is in radians)
tan x	Tangent of x (in radians)
tanh x	Hyperbolic tangent of x (x is in radians)
x ? y : z	Ternary conditional (if x then y else z)

Operator

Description

Factorial (x * (x-1) * (x-2) * … * 2 * 1). gamma(x + 1) for non-integers

abs x

The absolute value of x

ceil x

Round to the next integer

floor x

Round to the previous integer

length x

String length of x

round x

Round to the nearest integer

sqrt x

Square root of x

trunc x

Remove the fractional part of x

exp x

e^x (exponential/antilogarithm function with base e)

ln x or log x

Natural logarithm of x

log10 x

Base-10 logarithm of x

acos x

Arc cosine of x (in radians)

acosh x

Hyperbolic arc cosine of x (in radians)

asin x

Arc sine of x (in radians)

asinh x

Hyperbolic arc sine of x (in radians)

atan x

Arc tangent of x (in radians)

atanh x

Hyperbolic arc tangent of x (in radians)

cos x

Cosine of x (in radians)

cosh x

Hyperbolic cosine of x (in radians)

sin x

Sine of x (in radians)

sinh x

Hyperbolic sine of x (x is in radians)

tan x

Tangent of x (in radians)

tanh x

Hyperbolic tangent of x (x is in radians)

x ? y : z

Ternary conditional (if x then y else z)

Functions

Function	Description
random(n)	Get a random number in the range [0, n). If n is equal to zero, or not provided, it defaults to 1.
min(a,b,…)	Get the smallest (minimum) number in the list.
max(a,b,…)	Get the largest (maximum) number in the list.
hypot(a,b) or pyt(a, b)	Hypotenuse – the square root of the sum of squares of its arguments (sqrt(a^2+b2)).
pow(x, y)	Equivalent of exponentiation x^y.
atan2(y, x)	Arc tangent of x/y – the angle between (0, 0) and (x, y) in radians.
if(x, y, z)	Equivalent of the ternary conditional (if x then y else z).
delta(x)	Difference between the current and the previous value of the x.
deltaRoll(x)	Only positive difference between the current and the previous value of the x. Negative value is replaced with the last non-negative result.
timestamp()	Timestamp of each metric from the returned series of values. The format is 13-digit integer value (milliseconds).

Function

Description

random(n)

Get a random number in the range [0, n). If n is equal to zero, or not provided, it defaults to 1.

min(a,b,…)

Get the smallest (minimum) number in the list.

max(a,b,…)

Get the largest (maximum) number in the list.

hypot(a,b) or
pyt(a, b)

Hypotenuse – the square root of the sum of squares of its arguments (sqrt(a^2+b2)).

pow(x, y)

Equivalent of exponentiation x^y.

atan2(y, x)

Arc tangent of x/y – the angle between (0, 0) and (x, y) in radians.

if(x, y, z)

Equivalent of the ternary conditional (if x then y else z).

delta(x)

Difference between the current and the previous value of the x.

deltaRoll(x)

Only positive difference between the current and the previous value of the x. Negative value is replaced with the last non-negative result.

timestamp()

Timestamp of each metric from the returned series of values. The format is 13-digit integer value (milliseconds).