Skip to content

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.

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 An email address to which notifications are sent when the alarm is triggered. john.doe@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.

from requests import post, get, put, delete

project_id = 4
api_url = 'https://api.aedifion.io'
auth_john = ("john.doe@aedifion.com", "mys3cr3tp4ssw0rd")
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(f"{api_url}/v2/project/{project_id}/alert",
         auth=auth_john,
         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",
          "dataPointID": "bacnet100-4120-CO2",
          "threshold_dead": 100,
          "threshold_ok": 900,
          "threshold_crit": 1300, 
          "threshold_order": "asc", 
          "period": "2h"
        }'
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Project tag, then the POST /v2/project/{project_id}/alert endpoint (green).
  4. Enter the following JSON example in the newalert field:
    {
      "name": "CO2_Office100",
      "alert_type": "threshold",
      "telegram_chatid": "-219643311",
      "email": "john.doe%40aedifion.com",
      "dataPointID": "bacnet100-4120-CO2",
      "threshold_dead": 100,
      "threshold_ok": 900,
      "threshold_crit": 1300, 
      "threshold_order": "asc", 
      "period": "2h"
    }
    
  5. Click "Try it out!".
  6. Inspect the response body and code.

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.

Parameter 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 An email address to which notifications are sent when the alarm is triggered. john.doe@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
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"    
        }'
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Project tag, then the POST /v2/project/{project_id}/alert endpoint (green).
  4. Enter the following JSON example in the newalert field:
    {
      "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"
    }
    
  5. Click "Try it out!".
  6. Inspect the response body and code.

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"
        }'
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Project tag, then the PUT /v2/project/{project_id}/alert/{alert_id} endpoint (yellow).
  4. Provide the project_id, alert_id as well as the param and its value.
  5. Click "Try it out!".
  6. Inspect the response body and code.

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

telegram-project
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.

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

telegram-reply
Figure 3: Replying to a selected alert in Telegram

  1. 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.).
  2. Select how much history you need.

telegram-history
Figure 4: Select how much history you need

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

telegram-plot
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.

throughput-reply
Figure 6: Replying to a throughput alert

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

throughput-plot
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
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Project tag, then the PUT /v2/project/{project_id}/alert/{alert_id}/toggle endpoint (yellow).
  4. Provide the project_id and alert_id.
  5. Click "Try it out!".
  6. Inspect the response body and code.

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
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Project tag, then the GET /v2/project/{project_id}/alerts endpoint (blue).
  4. Provide the project_id.
  5. Click "Try it out!".
  6. Inspect the response body and code.

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
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Project tag, then the DELETE /v2/project/{project_id}/alert/{alert_id} endpoint (red).
  4. Provide the project_id and alert_id.
  5. Click "Try it out!".
  6. Inspect the response body and code.

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.


Last update: