General functionality

Alarms are used to observe incoming values of thing properties and trigger automatic reactions to unusual ones. The value type of the property therefore determines the type of values users can use for comparison. Numerical, string and boolean values may be used for evaluation. Detailed information on how to manage alarms in the IotHub can be found here.

Information on alarm lifecycles, histories and on what to do once an alarm has been activated can be found here.

As a reaction to an activated alarm either an e-mail can be sent or a web-hook triggered. Further information about reactions and reaction templates can be found here.

Alarm properties

In addition to the connection to a things' property alarms can have a title, a description and the following properties:

Level

Users can define multiple alarms on each property (identified by property name and thing id) by declaring a level for each instance. The level can have a domain specific range of values (like LL, L, H, HH for the chemical industry) or a generic set like Fatal, Critical and so on. The level name must be unique for a specific property but can be reused for other properties.

Limits

are represented by numerical, string or boolean expressions depending on the value type of the observed property. For string and boolean types only the two operators "equal" (=) and "not equal" (!=) can be used, numerical values also allow for more comparison options.

Observe-time

determines over what period of time values are evaluated. Setting the value to 0 results in immediate activation of standard alarms for each outlier. Average and no-value alarms have a minimum observe-time of 100ms.

Deadbands

are used to define value ranges for number values. Half the deadband value will be added to and subtracted from the limit to form the range. Using a percentage values defines the deviation from the limit. (See the bottom of this page for examples)

Severity

In addition to the user defined level alarms have a severity property used to easily indicate the assumed severity of an issue. However, there is no underlying functionality and values should be chosen according to user preference. An example definition would be:

Icon	Severity	Description
	Info	The alarm just informs about a state change of the thing.
	Warning	The value of the property indicates some issue that might need follow-up.
	Error	The alarm indicates an error state in the thing.
	Critical	The value is in a range where damaging something is possible (e.g. close to smelting temperatures).

Alarm Types

Alarms can have one of three types each representing a different trigger mechanism. Limit (incl. operator), observe-time and deadband define the trigger behavior.

Standard

alarms observe only the latest value. Whenever a value is received it will be evaluated against the trigger value defined by an operator and a limit. The observe-time is used to raise an alarm only if the trigger is in its activation range for at least the specified amount of time to be able to ignore single outliers.

Average

alarms calculate the average of all received values within the observe-time. Recalculation occurs upon receiving new values and those received longer ago than the observe-time will be ignored.

The sensible selection of the right observe-time is very important and should be directly related to the frequency of incoming values. A period which is too short might result in the evaluation of only one value while a period longer than necessary might lead to not raising the alarm as often as required.

No Value

This alarm type is triggered whenever there are no incoming values over a period of time.

Examples

Imagine having a sensor usually sending numeric values every second withing the range of 10 to 20.

Standard Alarm

This example describes a standard alarm which activates whenever the value range is exceeded for more than 5 seconds. The limit is set to 15 with a deadband of 10 or 33.33% which defines the range from 10 to 20. The unequal operator (!=) sets the alarm to be triggered by values outside the defined range. Setting the observe-time to 5000 ms completes the configuration of the alarm.

Deadbands

can be set as numerical or percentage value. Numerical values define the whole range around the limit meaning half of the deadband is added to and half is subtracted from the limit. A percentage value defines the deviation from the limit meaning 10% resulting in a range from 0.9 to 1.1 times the limit.

Standard Alarm Example

Time	Explanation
3s	The value exceeds the range.
6s	After only 3 seconds it returns back to normal levels. Since the observe time was not exceeded there is no alarm activation.
9s	The values once again exceed the defined range.
14s	The alarm is activated as the values did not return to normal
19s	Once again the values return to normal and the state returns to idled.

Average Alarm

As an addition to the first example a second alarm could be raised whenever the average of the incoming values exceeds a limit of 19 for 5s or more. This could indicate that the upper limit is often exceeded just not long enough to raise the first alarm. The operator would be greater than (>) and the observe-time stays at 5000 ms. Average alarms do not use a deadband.

Average Alarm Example

Time	Explanation
5s	The first time a value comes in raising the average above 19.
7s	The average returns below 19.
9s	Once again the average exceeds the limit.
14s	The alarm is activated after 5 seconds due to the still exceeded average.
20s	Once again the average return to normal and the state returns to idled.

No-Value Alarm

The last alarm should be activated whenever there has been no values received over a period of 5 seconds. Limit and deadband are not used as the evaluation is about whether there are values or not. The observe-time should be set once more to 5000 ms.

No-Value Alarm Example

Time	Explanation
5s - 7s	A short period of no values not exceeding the observe time.
9s	Here starts the period with no values.
14s	After 5 seconds the alarm is activated.
20s	The alarm returns to idled once again.