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. Three severity levels are supported: info, warning, and critical. Each level can optionally have a separate reset threshold to implement hysteresis and prevent flapping. 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 crosses certain thresholds. Throughput is measured in values per second over a configurable time period. Three severity levels (info, warning, critical) indicate the severity of abnormal throughput. Please contact us to get to know your 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¶

Threshold and throughput alarms are created through separate endpoints. The parameters that specify the alarm must be encoded as a JSON object and sent in the body of the request.

Adding a threshold alarm¶

A new threshold alarm is created through the POST /v2/alert/threshold endpoint. The project_id is passed as a query parameter.

Threshold alarms are defined through the following parameters.

Threshold order is automatically determined from the provided threshold values:

• If info < warn < crit, the order is ascending — the alert gets more critical as values increase.
• If info > warn > crit, the order is descending — the alert gets more critical as values decrease.

Reset thresholds implement hysteresis. For example, with an ascending alert, a critical alert triggers when observations exceed thresholds.crit and resets only when they fall below thresholds.crit_reset. This prevents the alert from rapidly toggling on and off when values hover around a threshold. If you do not need hysteresis, simply omit the reset values — they will default to the trigger values.

Let's add a threshold alarm on CO2 concentration and see what happens.

from requests import post, get, delete

project_id = 4
api_url = 'https://api3.aedifion.io'
auth_john = ("john.doe@aedifion.com", "mys3cr3tp4ssw0rd")
newalert = {
    "name": "CO2_Office100",
    "description": "Alert on indoor CO2 level with three severity levels.",
    "dataPointID": "bacnet100-4120-CO2",
    "thresholds": {
        "info": 600,
        "info_reset": 500,
        "warn": 1000,
        "warn_reset": 900,
        "crit": 2500,
        "crit_reset": 2000
    },
    "repeat": "2h",
    "notification": {
        "email": {
            "recipients": ["john.doe@aedifion.com"]
        },
        "telegram": {
            "chat_ids": ["-219643311"]
        },
        "dashboard": {
            "enabled": False
        }
    },
    "attributes": {
        "category": "comfort",
        "team": "Operations"
    }
}

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

print(r.status_code, r.text)

curl "https://api3.aedifion.io/v2/alert/threshold?project_id=4"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json'
    -d '{
          "name": "CO2_Office100",
          "description": "Alert on indoor CO2 level with three severity levels.",
          "dataPointID": "bacnet100-4120-CO2",
          "thresholds": {
              "info": 600,
              "info_reset": 500,
              "warn": 1000,
              "warn_reset": 900,
              "crit": 2500,
              "crit_reset": 2000
          },
          "repeat": "2h",
          "notification": {
              "email": {
                  "recipients": ["john.doe@aedifion.com"]
              },
              "telegram": {
                  "chat_ids": ["-219643311"]
              },
              "dashboard": {
                  "enabled": false
              }
          },
          "attributes": {
              "category": "comfort",
              "team": "Operations"
          }
        }'

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

{
  "id": 6,
  "name": "CO2_Office100",
  "description": "Alert on indoor CO2 level with three severity levels.",
  "alert_type": "threshold",
  "project_id": 4,
  "status": "Enabled",
  "created": "2024-01-15T10:30:00.000000Z",
  "updated": "2024-01-15T10:30:00.000000Z",
  "dataPointID": "bacnet100-4120-CO2",
  "threshold_info": 600,
  "threshold_info_reset": 500,
  "threshold_warn": 1000,
  "threshold_warn_reset": 900,
  "threshold_crit": 2500,
  "threshold_crit_reset": 2000,
  "threshold_order": "asc",
  "period": "2h",
  "email": "john.doe@aedifion.com",
  "telegram_chatid": "-219643311",
  "alarm_dashboard": false,
  "attributes": {"category": "comfort", "team": "Operations"}
}

Note that the alarm has received a unique numeric id (6) and has been enabled immediately. The repeat value you provided during creation is returned as period in the response.

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. But first, we will add an alarm of the second type, i.e., throughput. Later, we will also look at how to test your alarms by deliberately setting low thresholds.

Adding a throughput alarm¶

A new throughput alarm is created through the POST /v2/alert/throughput endpoint. The project_id is passed as a query parameter.

Throughput alarms are defined through the following parameters.

As with threshold alarms, the threshold order is automatically determined:

• If info < warn < crit, the alert gets more critical as throughput grows (ascending).
• If info > warn > crit, the alert gets more critical as throughput drops (descending).

newalert = {
    "name": "EON_ERC_Throughput",
    "description": "Alert on project data ingress throughput.",
    "thresholds": {
        "info": 50,
        "info_reset": 60,
        "warn": 20,
        "warn_reset": 25,
        "crit": 0,
        "crit_reset": 2
    },
    "period": "10m",
    "repeat": "1d",
    "notification": {
        "email": {
            "recipients": ["john.doe@aedifion.com"]
        },
        "telegram": {
            "chat_ids": ["-219643311"]
        }
    }
}

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

print(r.status_code, r.text)

curl "https://api3.aedifion.io/v2/alert/throughput?project_id=4"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json'
    -d '{
          "name": "EON_ERC_Throughput",
          "description": "Alert on project data ingress throughput.",
          "thresholds": {
              "info": 50,
              "info_reset": 60,
              "warn": 20,
              "warn_reset": 25,
              "crit": 0,
              "crit_reset": 2
          },
          "period": "10m",
          "repeat": "1d",
          "notification": {
              "email": {
                  "recipients": ["john.doe@aedifion.com"]
              },
              "telegram": {
                  "chat_ids": ["-219643311"]
              }
          }
        }'

The response (HTTP 201) confirms the creation:

{
  "id": 7,
  "name": "EON_ERC_Throughput",
  "description": "Alert on project data ingress throughput.",
  "alert_type": "throughput",
  "project_id": 4,
  "status": "Enabled",
  "created": "2024-01-15T11:00:00.000000Z",
  "updated": "2024-01-15T11:00:00.000000Z",
  "dataPointID": "",
  "threshold_info": 50,
  "threshold_info_reset": 60,
  "threshold_warn": 20,
  "threshold_warn_reset": 25,
  "threshold_crit": 0,
  "threshold_crit_reset": 2,
  "threshold_order": "desc",
  "period": "10m",
  "email": "john.doe@aedifion.com",
  "telegram_chatid": "-219643311",
  "alarm_dashboard": false,
  "attributes": ""
}

Since no dataPointID was provided, the throughput of the whole project is measured.

Testing your alarms¶

The previous alarm might have been set too defensively and not trigger unless there is a small party going on in your office. To provoke a threshold alarm and verify it works, you can create an alert with deliberately low thresholds that will trigger immediately, e.g., set "crit": 200 for a CO2 sensor that normally reads above 400 ppm. You may also try to provoke some alerts by gathering a few people in your office or by directly breathing into the CO2 sensor. You will soon see alerts from @aedifion_bot arriving in your Telegram chat (or to your email).

Figure 1: Telegram alerts on CO2 concentration in action

Similarly, you can provoke a throughput alarm by setting very high thresholds, e.g., "crit": 20000, "warn": 50000 and "info": 100000.

Figure 2: Telegram alert on project throughput in action

Modifying alarms¶

Enabling and disabling alarms¶

Since the alarm might now be triggering notifications frequently, let's take a break and disable it. You can disable an alarm to temporarily stop it from sending notifications, and enable it again later. There are two separate endpoints for this: POST /v2/alert/{alert_id}/disable and POST /v2/alert/{alert_id}/enable.

Disabling an alarm¶

alert_id = 6
r = post(f"{api_url}/v2/alert/{alert_id}/disable",
         auth=auth_john)
print(r.status_code, r.text)

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

The response (HTTP 200) returns the alert with its updated status:

{
  "id": 6,
  "name": "CO2_Office100",
  "description": "Alert on indoor CO2 level with three severity levels.",
  "alert_type": "threshold",
  "project_id": 4,
  "status": "Disabled",
  "created": "2024-01-15T10:30:00.000000Z",
  "updated": "2024-01-15T10:35:00.000000Z",
  "dataPointID": "bacnet100-4120-CO2",
  "threshold_info": 600,
  "threshold_info_reset": 500,
  "threshold_warn": 1000,
  "threshold_warn_reset": 900,
  "threshold_crit": 2500,
  "threshold_crit_reset": 2000,
  "threshold_order": "asc",
  "period": "2h",
  "email": "john.doe@aedifion.com",
  "telegram_chatid": "-219643311",
  "alarm_dashboard": false,
  "attributes": {"category": "comfort", "team": "Operations"}
}

Enabling an alarm¶

To re-enable the alarm, use the enable endpoint:

alert_id = 6
r = post(f"{api_url}/v2/alert/{alert_id}/enable",
         auth=auth_john)
print(r.status_code, r.text)

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

The response (HTTP 200) returns the alert with "status": "Enabled".

Listing alarms¶

You can list all alarms using the GET /v2/project/{project_id}/alerts endpoint. The response is paginated and supports filtering, searching, and sorting.

r = get(f"{api_url}/v2/project/{project_id}/alerts",
        auth=auth_john,
        params={"per_page": 50})
print(r.status_code, r.text)

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

The response is a paginated object containing a list of alerts and pagination metadata. Among them, we find the alarms we defined previously. Note that the previously disabled alarm has "status": "Disabled" because we paused it earlier.

{
  "items": [
    {
      "id": 6,
      "name": "CO2_Office100",
      "description": "Alert on indoor CO2 level with three severity levels.",
      "alert_type": "threshold",
      "project_id": 4,
      "status": "Disabled",
      "created": "2024-01-15T10:30:00.000000Z",
      "updated": "2024-01-15T10:35:00.000000Z",
      "dataPointID": "bacnet100-4120-CO2",
      "threshold_info": 600,
      "threshold_info_reset": 500,
      "threshold_warn": 1000,
      "threshold_warn_reset": 900,
      "threshold_crit": 2500,
      "threshold_crit_reset": 2000,
      "threshold_order": "asc",
      "period": "2h",
      "email": "john.doe@aedifion.com",
      "telegram_chatid": "-219643311",
      "alarm_dashboard": false,
      "attributes": {"category": "comfort", "team": "Operations"}
    },
    {
      "id": 7,
      "name": "EON_ERC_Throughput",
      "description": "Alert on project data ingress throughput.",
      "alert_type": "throughput",
      "project_id": 4,
      "status": "Enabled",
      "created": "2024-01-15T11:00:00.000000Z",
      "updated": "2024-01-15T11:00:00.000000Z",
      "dataPointID": "",
      "threshold_info": 50,
      "threshold_info_reset": 60,
      "threshold_warn": 20,
      "threshold_warn_reset": 25,
      "threshold_crit": 0,
      "threshold_crit_reset": 2,
      "threshold_order": "desc",
      "period": "10m",
      "email": "john.doe@aedifion.com",
      "telegram_chatid": "-219643311",
      "alarm_dashboard": false,
      "attributes": ""
    }
  ],
  "meta": {
    "total_items": 2,
    "items_per_page": 50,
    "current_page": 1,
    "total_pages": 1
  }
}

You can also filter results, for example to show only threshold alarms:

r = get(f"{api_url}/v2/project/{project_id}/alerts",
        auth=auth_john,
        params={"filter": "alert_type=threshold"})
print(r.text)

curl "https://api3.aedifion.io/v2/project/4/alerts?filter=alert_type%3Dthreshold"
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

Deleting alarms¶

Deleting an alarm is a simple matter of calling DELETE /v2/alert/{alert_id}. The response is HTTP 204 (No Content) with an empty body.

As an example, we now delete the threshold alarm that we have previously created.

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

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

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