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 a whole project. 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. Please contact us to get to know you project's typical data throughput. A typical use case 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 sent 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.

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.

from requests import post, get, put, delete

project_id = 4
api_url = 'https://api.aedifion.io'
auth_john = ("john.doe@aedifion.com", "mys3cr3tp4ssw0rd")
params = {'dataPointID': 'bacnet100-4120-CO2'}
newalert = {
    'name': 'CO2_Office100',
    'alert_type': 'threshold',
    'telegram_chatid': '-219643311',
    'email': 'john.doe@aedifion.com',
    'threshold_dead': 100,
    'threshold_ok': 900,
    'threshold_crit': 1300,
    'threshold_order': 'asc',
    'period': '2h'    
}

r = post(f"{api_url}/v2/project/{project_id}/alert",
         auth=auth_john,
         params=params,
         json=newalert)

print(r.text)

curl "https://api3.aedifion.io/v2/project/4/alert?dataPointID='bacnet100-4120-CO2'"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json' --header 'Accept: application/json'
    -d '{
          "name": "CO2_Office100",
          "alert_type": "threshold",
          "telegram_chatid": "-219643311",
          "email": "john.doe%40aedifion.com",
          "threshold_dead": 100,
          "threshold_ok": 900,
          "threshold_crit": 1300, 
          "threshold_order": "asc", 
          "period": "2h"
        }'

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. But first, we will add an alarm of the second type, i.e., throughput.

Adding a throughput alarm¶

Throughput alarms are defined through the following parameters.

project_id = 4
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(f"{api_url}/v2/project/{project_id}/alert",
         auth=auth_john,
         json=newalert)

print(f"{r.status_code} - {r.text}")

curl "https://api3.aedifion.io/v2/project/4/alert?dataPointID='bacnet100-4120-CO2'"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json' --header 'Accept: application/json'
    -d '{
          "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"    
        }'

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
  }
}

Modifying alarms¶

The previous alarm might have been set to defensively and not trigger unless there is a small party going on in your office. Here the PUT /v2/project/{project_id}/alert/{alert_id} endpoint provides modification of existing alarms. 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.

alert_id = 6
updatealert = {
    'threshold_ok': 100,
    'threshold_crit': 200,
    'period': '30s'
}

r = put(f"{api_url}/v2/project/{project_id}/alert/{alert_id}",
        auth=auth_john,
        json=updatealert)

print(r.text)

curl "https://api3.aedifion.io/v2/project/4/alert/6"
    -X PUT
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json' --header 'Accept: application/json'
    -d '{
          "threshold_ok": 100,
          "threshold_crit": 200,
          "period": "30s"
        }'

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).

Figure 1: 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.

Figure 2: 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.

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

Figure 3: Replying to a selected alert in Telegram

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.

Figure 4: Select how much history you need

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

Figure 5: Generated alert plot

In this example, we can observe that the 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.

Figure 6: Replying to a throughput alert

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

Figure 7: Generated throughput alert plot

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.

alert_id = 6
r = put(f"{api_url}/v2/project/{project_id}/alert/{alert_id}/toggle", 
        auth=auth_john)
print(r.text)

curl "https://api3.aedifion.io/v2/project/4/alert/6/toggle"
    -X PUT
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

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.

r = get(f"{auth_john}/v2/project/{project_id}/alerts")
print(r.text)

curl "https://api3.aedifion.io/v2/project/4/alerts"
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

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.

alert_id = 6 
r = delete(f"{api_url}/v2/project/{project_id}/alert/{alert_id}", 
           auth=auth_john)
print(r.text)

curl "https://api3.aedifion.io/v2/project/4/alert/6"
    -X DELETE
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

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 also delete the throughput alarm then call GET /v2/project/{project_id}/alerts to verify that both alarms are really gone.