[docs] Added documentation for default alert settings #611

Closes #611

Author: pandafy

docs/index.rst

@@ -41,6 +41,7 @@ the OpenWISP architecture.
     ./user/device-health-status.rst
     ./user/metrics.rst
     ./user/checks.rst
+    ./user/alerts.rst
     ./user/device-checks-and-alert-settings
     ./user/configuring-iperf3-check.rst
     ./user/dashboard-monitoring-charts.rst

docs/user/alerts.rst

@@ -0,0 +1,175 @@
+Alerts
+======
+
+.. contents:: **Table of contents**:
+    :depth: 2
+    :local:
+
+An alert is triggered when a device metric (e.g., ping, CPU usage) crosses
+its configured threshold for a specified duration (tolerance). A recovery
+alert is sent when the metric returns to normal.
+
+Alerts are based on **Alert Settings** defined for each metric, each
+setting includes:
+
+- **Operator**: defines the condition to evaluate the metric value:
+
+  - **Greater than**: triggers when the value exceeds the threshold.
+  - **Less than**: triggers when the value is below the threshold.
+
+- **Threshold**: the metric value that triggers the alert.
+- **Tolerance**: the duration (in minutes) for which the threshold must be
+  breached before an alert is triggered.
+
+OpenWISP Monitoring provides built-in alerts for the following metrics:
+
+.. note::
+
+    You can override the default alert settings globally using the
+    :ref:`openwisp_monitoring_metrics` setting, or on a per-device basis
+    as explained in the :doc:`device-checks-and-alert-settings` section.
+
+.. _ping_alert:
+
+Ping
+----
+
+Triggers when the device becomes unreachable via ping. This alert is
+enabled by default.
+
+**Default Alert Settings:**
+
+========= =================
+Operator  ``< (less than)``
+Threshold ``1``
+Tolerance ``0`` minutes
+========= =================
+
+.. note::
+
+    The :ref:`ping_check` check should be enabled for the device to
+    receive this alert.
+
+.. _configuration_applied_alert:
+
+Config Applied
+--------------
+
+Triggers when the device fails to apply configuration changes within the
+specified time. This alert is enabled by default.
+
+**Default Alert Settings:**
+
+========= =================
+Operator  ``< (less than)``
+Threshold ``1``
+Tolerance ``5`` minutes
+========= =================
+
+.. note::
+
+    The :ref:`config_applied_check` check should be enabled for the device
+    to receive this alert.
+
+.. _monitoring_data_collected_alert:
+
+Data Collected
+--------------
+
+Triggers when no metric data has been collected from the device. This
+alert is enabled by default.
+
+**Default Alert Settings:**
+
+========= =================
+Operator  ``< (less than)``
+Threshold ``1``
+Tolerance ``30`` minutes
+========= =================
+
+.. note::
+
+    The :ref:`monitoring_data_collected_check` check should be enabled for
+    the device to receive this alert.
+
+CPU Usage
+---------
+
+Triggers when CPU usage exceeds the threshold. This alert is enabled by
+default.
+
+**Default Alert Settings:**
+
+========= ====================
+Operator  ``> (greater than)``
+Threshold ``90`` (percent)
+Tolerance ``5`` minutes
+========= ====================
+
+Memory Usage
+------------
+
+Triggers when memory usage exceeds the threshold. This alert is enabled by
+default.
+
+**Default Alert Settings:**
+
+========= ====================
+Operator  ``> (greater than)``
+Threshold ``95`` (percent)
+Tolerance ``5`` minutes
+========= ====================
+
+Disk Usage
+----------
+
+Triggers when disk usage exceeds the threshold. This alert is enabled by
+default.
+
+**Default Alert Settings:**
+
+========= ====================
+Operator  ``> (greater than)``
+Threshold ``90`` (percent)
+Tolerance ``0`` minutes
+========= ====================
+
+.. _wifi_clients_alert:
+
+WiFi Clients (Max)
+------------------
+
+Triggers when the number of connected WiFi clients exceeds the threshold.
+This alert is disabled by default.
+
+**Default Alert Settings:**
+
+========= ====================
+Operator  ``> (greater than)``
+Threshold ``50``
+Tolerance ``120`` minutes
+========= ====================
+
+.. note::
+
+    The :ref:`wifi_clients_check` check should be enabled for the device
+    to receive this alert.
+
+WiFi Clients (Min)
+------------------
+
+Triggers when the number of connected WiFi clients falls below the
+threshold. This alert is disabled by default.
+
+**Default Alert Settings:**
+
+========= =================
+Operator  ``< (less than)``
+Threshold ``1``
+Tolerance ``0`` minutes
+========= =================
+
+.. note::
+
+    The :ref:`wifi_clients_check` check should be enabled for the device
+    to receive this alert.

docs/user/checks.rst

@@ -19,6 +19,9 @@ choose to disable auto creation of this check by setting
 You can change the default values used for ping checks using
 :ref:`openwisp_monitoring_ping_check_config` setting.
 
+This check also :ref:`sends an alert when the device becomes unreachable
+<ping_alert>`.
+
 .. _config_applied_check:
 
 Configuration Applied
@@ -35,6 +38,9 @@ configuration status of a device changes, this ensures the check reacts
 quickly to events happening in the network and informs the user promptly
 if there's anything that is not working as intended.
 
+This check also :ref:`sends an alert if configuration is not being applied
+<configuration_applied_alert>`.
+
 .. _monitoring_data_collected_check:
 
 Monitoring Data Collected
@@ -45,6 +51,9 @@ devices in a timely manner. You may choose to disable auto creation of
 this check by using the setting
 :ref:`openwisp_monitoring_auto_data_collected_check`.
 
+This check also :ref:`sends an alert when no data is received from a
+device <monitoring_data_collected_alert>`.
+
 .. _iperf3_check:
 
 Iperf3
@@ -109,3 +118,6 @@ You can use the
 :ref:`openwisp_monitoring_wifi_clients_check_snooze_schedule` setting to
 disable this check on specific dates, such as during scheduled
 maintenance, to avoid generating unnecessary alerts.
+
+This check also :ref:`sends alerts based on WiFi client thresholds
+<wifi_clients_alert>`.