Alarming

Tutorial for creating and managing alerts on time series and meta-data.

Overview

In this article, you will learn how to set up alarms on time series and meta-data on the aedifion.io platform. Currently, the aedifion.io platform supports two types of alarms: i) alarms on the observations for a datapoint and ii) alarms on the throughput (i.e., received observations per time interval) of a certain datapoint or whole project (please refer to our Glossary if the terms datapoint and observation seem strange to you). You will specify one of each and configure it to send out notifications on alarm events via the Telegram instant messenger or email.

Preliminaries

The examples provided in this article partly build on each other. For the sake of brevity, boiler plate code such as imports or variable definitions is only shown once and left out in subsequent examples.

To execute the examples provided in this tutorial, the following is needed:

  • A valid login (username and password) to the aedifion.io platform. If you do not have a login yet, please contact us regarding a demo login. The login used in the example will not work!

  • A project with live data ingress.

  • Optionally, a working installation of Python or Curl.

Types of alarms

The aedifion.io platform supports two versatile types of alarms:

  • Threshold alarms are defined on single datapoints and trigger an alarm whenever the measured values for that datapoint exceed (or fall below) a certain threshold. A typical use case for threshold alarms is notifying about unwanted system conditions such as high CO2 concentration in offices.

  • Throughput alarms are defined on single datapoints or whole projects and trigger an alarm whenever the measured throughput for that datapoint or project falls below a certain threshold. Thresholds can be set at three different levels to indicate the severity of missing throughput. Typical use cases for throughput alarms is fault detection by monitoring of the operational health of the building automation systems, e.g., alerting about the unscheduled shut-down of a critical component or notifying when a sensor is dead.

Further types of alarms will be added in future. If you have a special request, please contact us.

Adding alarms

A new alarm is created through the POST /v2/project/{project_id}/alert endpoint. The parameters that specify the alarm must be encoded as a JSON object and send in the body of the request. Since the list of parameters is quite involved, we start with the set of parameters for threshold alarms.

Adding a threshold alarm

Threshold alarms are defined through the following parameters.

Parameter

Datatype

Type

Required

Description

Example

name

string

body (JSON)

yes

The name of the new alarm. The name needs to be unique within the project scope.

CO2_Office-100

alert_ type

string

body

(JSON)

yes

The type of the alarm, either 'threshold' or 'throughput'.

threshold

telegram_ chatid

string

body (JSON)

no

The id of a Telegram chat where notifications are sent to when the alarm is triggered (must be a chat that involves @aedifion_bot)

-219643311

email

string

body

(JSON)

no

A comma-separated list of email recipients to which notifications are sent when the alarm is triggered.

john.doe@aedifion.com, jane.doe@aedifion.com,

alarm@aedifion.com

dataPointID

string

body

(JSON)

yes

The alphanumeric id of the datapoint on which to send alarms.

bacnet100-4120-CO2

threshold_ dead

float

body

(JSON)

yes

The threshold for observations below which the datapoint is considered dead, offline, or broken.

100

threshold_ ok

float

body

(JSON)

yes

The threshold for observations below which the datapoint is considered in correct state and any active alarm is reset.

900

threshold_ crit

float

body

(JSON)

yes

The threshold for observations above which the datapoint is considered to be in critical state.

1300

threshold_ order

string

body

(JSON)

no

The order of the thresholds. 'asc' as described, or 'desc' to reverse the order, basically flipping all comparisons.

asc

period

string

body

(JSON)

yes

The time period after which an alert is resent when in critical state (h = hours, m = minutes, s = seconds).

2h

Have you noted the gap between the threshold_ok and threshold_crit? This is called a hysteresis. The alarm will enter critical state once observations exceed the threshold_crit then fire warnings every 2 hours until observations fall below threshold_ok. Of course, you can set threshold_ok equal to threshold_crit if you want alarms to recover immediately when observations fall below the critical threshold.

Let's add the above alarm and see what happens.

Python
Curl
Swagger UI
from requests import post, get, put, delete
project_id = 4
api_url = "https://api.aedifion.io"
newalert = {
'name': 'CO2_Office100',
'alert_type': 'threshold',
'telegram_chatid': '-219643311',
'email': 'john.doe@aedifion.com',
'dataPointID': 'bacnet100-4120-CO2',
'threshold_dead': 100,
'threshold_ok': 900,
'threshold_crit': 1300,
'threshold_order': 'asc',
'period': '2h'
}
r = post(api_url + "/v2/project/{}/alert".format(project_id),
auth=john,
json=newalert)
print(r.text)

Coming soon 🐒

Coming soon 🐒

The JSON-formatted response confirms that the alarm was successfully created and returns the details of the alarm:

{
"success": true,
"operation": "create",
"resource": {
"created": "2018-11-22T15:34:14.292927751Z",
"dataPointID": "bacnet100-4120-CO2",
"email": "john.doe@aedifion.com",
"id": 6,
"name": "CO2_Office100",
"period":7200000000000,
"project_id": 4,
"status": "enabled",
"telegram_chatid": "-219643311",
"threshold_crit":1300,
"threshold_dead":100,
"threshold_ok":900
}
}

Note that the alarm has received a unique numeric id (6), the period of 2 hours has been translated into nanoseconds, and it has already been enabled.

You may already receive alarms or try to provoke some by gathering a few people in your office or by directly breathing into the CO2 sensor. Otherwise, don't worry, we will later modify the alarm such that it will definitely trigger alarms even without having a party in your office. Before, we add an alarm of the second type, i.e., throughput.

Adding a throughput alarm

Throughput alarms are defined through the following parameters.

Paramater

Datatype

Type

Required

Description

Example

name

string

body

(JSON)

yes

The name of the new alarm. Needs to be unique within the project scope.

CO2_Office-100

alert_ type

string

body

(JSON)

yes

The type of the alarm, either 'threshold' or 'throughput'.

threshold

telegram_ chatid

string

body (JSON)

no

The id of a Telegram chat where notifications are sent to when the alarm is triggered (must be a chat that involves @aedifion_bot)

-219643311

email

string

body

(JSON)

no

A comma-separated list of email recipients to which notifications are sent when the alarm is triggered.

john.doe@aedifion.com, jane.doe@aedifion.com,

alarm@aedifion.com

dataPointID

string

body

(JSON)

no

The alphanumeric id of the datapoint on which to measure throughput. If not provided, throughput of the whole project is measured.

bacnet100-4120-CO2

threshold_

info

float

body

(JSON)

yes

First threshold below which throughput is considered slightly lower than usual.

50

threshold_

warn

float

body

(JSON)

yes

Second threshold below which throughput is considered significantly lower than usual.

20

threshold_

crit

float

body

(JSON)

yes

Third threshold below which throughput is considered critically low.

10

period

string

body

(JSON)

yes

Time period over which to measure throughput (h = hours, m = minutes, s = seconds).

10m

Python
Curl
project_id = 4
api_url = "https://api.aedifion.io"
newalert = {
'name': 'EON_ERC_Throughput',
'alert_type': 'throughput',
'telegram_chatid': '-219643311',
'email': 'john.doe@aedifion.com',
'threshold_info': 1000,
'threshold_warn': 500,
'threshold_crit': 100,
'period': '30s'
}
r = post(api_url + "/v2/project/{}/alert".format(project_id),
auth=john,
json=newalert)
print(f"{r.status_code} - {r.text}")

As usual, the confirmation comes with the response.

{
"success":true,
"operation": "create",
"resource": {
"id":8,
"created": "2018-11-23T12:08:43.994355154Z",
"dataPointID": "bacnet100-4120-CO2",
"email": "john.doe@aedifion.com",
"name": "EON_ERC_Throughput",
"period":30000000000,
"project_id": 4,
"status": "enabled",
"telegram_chatid": "-219643311",
"threshold_crit": 1000,
"threshold_info": 500,
"threshold_warn": 100
}
}

We would now need to

Modifying alarms

The previous alarm might have been set to defensively and not trigger unless there is small party going on in your office. In order to provoke an alert, we now set a ridiculously low threshold_crit and also define a much shorter reminder period for the repetition of the alarms.

Python
Curl
Swagger UI
alert_id = 6
updatealert = {
'threshold_ok': 100,
'threshold_crit': 200,
'period': '30s'
}
r = put(api_url + f"/v2/project/{project_id}/alert/{alert_id}",
auth=john,
json=updatealert)
print(r.text)

Coming soon 🐒

Coming soon 🐒

The response confirms that the alarm has been updated as requested:

{
"success": true,
"operation": "update",
"resource": {
"id":6,
"created": "2018-11-22T15:34:14.292927751Z",
"dataPointID": "bacnet100-4120-CO2",
"email": "john.doe@aedifion.com",
"name": "CO2_Office100",
"period": 30000000000,
"project_id": 4,
"status": "enabled",
"telegram_chatid": "-219643311",
"threshold_crit": 200,
"threshold_dead": 100,
"threshold_ok": 900
}
}

You will soon see the alerts from @aedifion_bot dropping in to your Telegram chat (or to your mail account).

Telegram alerts on CO2 concentration in action

We can also modify the throughput alarm with ridiculously high thresholds on throughput to provoke an alarm, e.g., "threshold_crit": 20000."threshold_warn": 50000 and "threshold_info": 100000.

Telegram alert on project throughput in action

Plotting alarms in Telegram

When we receive an alarm, e.g., on Telegram, we want to get a quick idea of what triggered the alarm. The first thing is then to actually look at the time series. Conveniently, we can do this through @aedifion_bot right there in Telegram where the alerts are received.

Due to data privacy protection, the plotting feature must first be activated for your Telegram chat. Please contact the technical support in this matter. If it is not yet activated you will receive an error message accordingly.

Plotting a threshold alarm

Follow the next four steps to plot the time series of a datapoint on which a threshold alert was triggered:

  1. Right-click on one of the alarms and hit Reply

2. Reply to the selected alert with the message "/plot" (messages starting with a slash / are interpreted as commands to the bot by the Telegram Bot API.).

3. Select how much history you need.

4. Wait for the plot to be generated and inspect it.

In this example, we can observe that CO2 level started to rise rapidly with the beginning of the workday. This is quite normal and nothing to worry about.

Plotting a throughput alarm

You can also plot throughput in exactly the same manner as plotting threshold alarms - you only need to reply "/plot" to a throughput alarm notification sent by the bot.

As before, select the amount of history you need and wait for the plot be received.

Pausing alarms

Since the alarm is now triggering notifications every 30 seconds, let's take a break and pause the alarm. The PUT /v2/project/{project_id}/alert/{alert_id}/toggle endpoint is a shorthand for this task.

Python
Curl
Swagger UI
alert_id = 6
r = put(api_url + f"/v2/project/{project_id}/alert/{alert_id}/toggle",
auth=john)
print(r.text)

Coming soon 🐒

Coming soon 🐒

The response tells us that the alarm has been switched off.

{
"success": true,
"operation": "update",
"resource": "Alert switched off!"
}

Calling the endpoint a second time, would switch the alarm back on again. But let's leave it switched off for now.

Listing alarms

You can list all alarms using the GET /v2/project/{project_id}/alerts endpoint.

Python
Curl
Swagger UI
r = get(api_url + f"/v2/project/{project_id}/alerts")
print(r.text)

Coming soon 🐒

Coming soon 🐒

The answer is a list of alarms among which we find the one we defined previously. Note that it has "status": "disabled" because we paused it.

[
...
{
"id":6,
"created": "2018-11-23T08:28:43.526937933Z",
"dataPointID": "bacnet100-4120-CO2",
"email": "john.doe@aedifion.com",
"name": "CO2_Office100",
"period": 30000000000,
"project_id": 4,
"status": "disabled",
"telegram_chatid": "-219643311",
"threshold_crit":200,
"threshold_dead":100,
"threshold_ok":100
},
{
"id":7,
"created": "2018-11-23T12:08:43.994355154Z",
"dataPointID": "bacnet100-4120-CO2",
"email": "john.doe@aedifion.com",
"name":"EON_ERC_Throughput",
"period":30000000000,
"project_id": 4,
"status": "enabled",
"telegram_chatid": "-219643311",
"threshold_crit": 20000,
"threshold_info":100000,
"threshold_warn":50000
},
...
]

Deleting alarms

Deleting an alarm is a simple matter of calling DELETE /v2/project/{project_id}/alert/{alert_id}. As an example, we now delete the threshold alarm that we have previously created and modified.

Python
Curl
Swagger UI
alert_id = 6
r = delete(api_url + f"/v2/project/{project_id}/alert/{alert_id}", auth=john)
print(r.text)

The response confirms the deletion and returns the details of the deleted alarm.

{
"success": true,
"operation": "delete",
"resource": {
"id":6,
"created": "2018-11-23T08:28:43.526937933Z",
"dataPointID": "bacnet100-4120-CO2",
"email": "john.doe@aedifion.com",
"name": "CO2_Office100",
"period": 30000000000,
"project_id": 4,
"status": "disabled",
"telegram_chatid": "-219643311",
"threshold_crit":200,
"threshold_dead":100,
"threshold_ok":100
}
}

Go ahead and delete also the throughput alarm then call GET /v2/project/{project_id}/alerts to verify that both alarms are really gone.