[docs] Improved docs: metrics, checks and alerts

Give priority to visuals, list general information first,
better interlinking of metrics, checks and alerts,
fixed minor issues with the wifi clients check section.

Author: nemesifier

docs/user/alerts.rst

@@ -5,6 +5,9 @@ Alerts
     :depth: 2
     :local:
 
+Introduction
+------------
+
 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.
@@ -22,21 +25,26 @@ setting includes:
   continuously breached before triggering an alert. Helps reduce noise
   from flapping metrics.
 
-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.
 
+The built-in alerts are explained below.
+
 .. _ping_alert:
 
 Ping
 ----
 
-Triggers when the device becomes unreachable via ping. This alert is
-enabled by default.
+Triggers when the device becomes unreachable via ping.
+
+**Alert enabled by default?** Yes.
+
+**Collected via**: :ref:`Ping Check <ping_check>`.
+
+**Charts**: :ref:`Ping Chart <ping>`.
 
 **Default Alert Settings:**
 
@@ -46,18 +54,17 @@ Threshold ``1``
 Tolerance ``30`` 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.
+specified time.
+
+**Alert enabled by default?** Yes.
+
+**Collected via**: :ref:`Config Applied Check <config_applied_check>`.
 
 **Default Alert Settings:**
 
@@ -67,18 +74,17 @@ Threshold ``1``
 Tolerance ``10`` 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.
+Triggers when no metric data has been collected from the device.
+
+**Alert enabled by default?** Yes.
+
+**Collected via**: :ref:`Config Applied Check
+<monitoring_data_collected_check>`.
 
 **Default Alert Settings:**
 
@@ -88,44 +94,63 @@ Threshold ``1``
 Tolerance ``30`` minutes
 ========= =================
 
-.. note::
+.. _memory_usage_alert:
 
-    The :ref:`monitoring_data_collected_check` check should be enabled for
-    the device to receive this alert.
+Memory Usage
+------------
+
+Triggers when memory usage exceeds the threshold.
 
-CPU Usage
----------
+**Alert enabled by default?** Yes.
 
-Triggers when CPU usage exceeds the threshold. This alert is enabled by
-default.
+**Collected via**: :doc:`OpenWrt Monitoring Agent
+</openwrt-monitoring-agent/index>`.
+
+**Charts**: :ref:`Memory Usage Chart <memory_usage>`.
 
 **Default Alert Settings:**
 
 ========= ====================
 Operator  ``> (greater than)``
-Threshold ``90`` (percent)
+Threshold ``95`` (percent)
 Tolerance ``30`` minutes
 ========= ====================
 
-Memory Usage
-------------
+.. _cpu_load_alert:
+
+CPU Load Average
+----------------
+
+Triggers when CPU usage exceeds the threshold.
+
+**Alert enabled by default?** Yes.
 
-Triggers when memory usage exceeds the threshold. This alert is enabled by
-default.
+**Collected via**: :doc:`OpenWrt Monitoring Agent
+</openwrt-monitoring-agent/index>`.
+
+**Charts**: :ref:`CPU Load Chart <cpu_load_averages>`.
 
 **Default Alert Settings:**
 
 ========= ====================
 Operator  ``> (greater than)``
-Threshold ``95`` (percent)
+Threshold ``90`` (percent)
 Tolerance ``30`` minutes
 ========= ====================
 
+.. _disk_usage_alert:
+
 Disk Usage
 ----------
 
-Triggers when disk usage exceeds the threshold. This alert is enabled by
-default.
+Triggers when disk usage exceeds the threshold.
+
+**Alert enabled by default?** Yes.
+
+**Collected via**: :doc:`OpenWrt Monitoring Agent
+</openwrt-monitoring-agent/index>`.
+
+**Charts**: :ref:`Disk Usage Chart <disk_usage>`.
 
 **Default Alert Settings:**
 
@@ -141,7 +166,13 @@ WiFi Clients (Max)
 ------------------
 
 Triggers when the number of connected WiFi clients exceeds the threshold.
-This alert is disabled by default.
+
+**Alert enabled by default?** No (see :ref:`WiFi Clients Check
+<wifi_clients_check>` for details on how to enable it).
+
+**Collected via**: the WiFi clients information is collected through the
+:doc:`OpenWrt Monitoring Agent </openwrt-monitoring-agent/index>`, but the
+alert is triggered by the :ref:`WiFi Clients Check <wifi_clients_check>`.
 
 **Default Alert Settings:**
 
@@ -151,16 +182,18 @@ 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.
+threshold.
+
+**Alert enabled by default?** No (see :ref:`WiFi Clients Check
+<wifi_clients_check>` for details on how to enable it).
+
+**Collected via**: the WiFi clients information is collected through the
+:doc:`OpenWrt Monitoring Agent </openwrt-monitoring-agent/index>`, but the
+alert is triggered by the :ref:`WiFi Clients Check <wifi_clients_check>`.
 
 **Default Alert Settings:**
 
@@ -169,8 +202,3 @@ 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

@@ -5,11 +5,31 @@ Checks
     :depth: 2
     :local:
 
+Introduction
+------------
+
+Active checks are periodic background tasks executed by `Celery workers
+<https://docs.celeryq.dev/en/stable/>`_ on the OpenWISP server.
+
+These workers perform the enabled checks and store their results in the
+time series database.
+
+The built-in checks and the related django settings available in OpenWISP
+Monitoring are described below.
+
+.. include:: /partials/settings-note.rst
+
 .. _ping_check:
 
 Ping
 ----
 
+**Check enabled by default?** Yes.
+
+**Alert**: :ref:`Ping Alert <ping_alert>`.
+
+**Charts**: :ref:`Ping Charts <ping>`.
+
 This check returns information on Ping Success Rate and RTT (Round trip
 time). It creates charts like Ping Success Rate, Packet Loss and RTT.
 These metrics are collected using the ``fping`` Linux program. You may
@@ -27,6 +47,10 @@ This check also :ref:`sends an alert when the device becomes unreachable
 Configuration Applied
 ---------------------
 
+**Check enabled by default?** Yes.
+
+**Alert**: :ref:`Config Applied Alert <configuration_applied_alert>`.
+
 This check ensures that the :doc:`openwisp-config agent
 </openwrt-config-agent/index>` is running and applying configuration
 changes in a timely manner. You may choose to disable auto creation of
@@ -46,6 +70,10 @@ This check also :ref:`sends an alert if configuration is not being applied
 Monitoring Data Collected
 -------------------------
 
+**Check enabled by default?** Yes.
+
+**Alert**: :ref:`Data Collected Alert <monitoring_data_collected_alert>`.
+
 This check ensures that the server is receiving metrics from network
 devices in a timely manner. You may choose to disable auto creation of
 this check by using the setting
@@ -59,13 +87,16 @@ device <monitoring_data_collected_alert>`.
 Iperf3
 ------
 
+**Check enabled by default?** No.
+
+**Charts**: :ref:`Iperf3 Charts <iperf3>`.
+
 This check provides network performance measurements such as maximum
 achievable bandwidth, jitter, datagram loss etc of the device using
 `iperf3 utility <https://iperf.fr/>`_.
 
 This check is **disabled by default**. You can enable auto creation of
-this check by setting the :ref:`openwisp_monitoring_auto_iperf3` to
-``True``.
+this check by setting :ref:`openwisp_monitoring_auto_iperf3` to ``True``.
 
 You can also :doc:`add the iperf3 check
 <device-checks-and-alert-settings>` directly from the device page.
@@ -87,6 +118,10 @@ parameters used for iperf3 checks (e.g. timing, port, username, password,
 WiFi Clients
 ------------
 
+**Check enabled by default?** No.
+
+**Alerts**: :ref:`WiFi Clients Alerts (Max/Min) <wifi_clients_alert>`.
+
 This check sends alerts based on the total number of WiFi Clients
 connected to a device. It sends two types of alerts:
 
@@ -102,14 +137,7 @@ connected to a device. It sends two types of alerts:
   connectivity.
 
 This check is **disabled by default**. To enable auto creation of this
-check, set :ref:`openwisp_monitoring_auto_wifi_clients_check` to ``True``
-and configure the task scheduling in your Django project:
-
-.. code-block:: python
-
-    from datetime import timedelta
-
-    OPENWISP_MONITORING_AUTO_WIFI_CLIENTS_CHECK = True
+check, set :ref:`openwisp_monitoring_auto_wifi_clients_check` to ``True``.
 
 You can also :doc:`add the WiFi Clients check
 <device-checks-and-alert-settings>` directly from the device page.
@@ -119,5 +147,7 @@ You can use the
 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>`.
+Other related settings:
+
+- :ref:`openwisp_monitoring_wifi_clients_max_check_interval`
+- :ref:`openwisp_monitoring_wifi_clients_min_check_interval`

docs/user/intro.rst

@@ -20,10 +20,11 @@ OpenWISP provides the following monitoring capabilities:
   :ref:`packet loss <ping_check>`, :ref:`round trip time (latency)
   <ping_check>`, :ref:`associated wifi clients <wifi_clients>`,
   :ref:`interface traffic <traffic>`, :ref:`RAM usage <memory_usage>`,
-  :ref:`CPU load <cpu_load>`, :ref:`flash/disk usage <disk_usage>`, mobile
-  signal (LTE/UMTS/GSM :ref:`signal strength <mobile_signal_strength>`,
-  :ref:`signal quality <mobile_signal_quality>`, :ref:`access technology
-  in use <mobile_access_technology_in_use>`), :ref:`bandwidth <iperf3>`,
+  :ref:`CPU load <cpu_load_averages>`, :ref:`flash/disk usage
+  <disk_usage>`, mobile signal (LTE/UMTS/GSM :ref:`signal strength
+  <mobile_signal_strength>`, :ref:`signal quality
+  <mobile_signal_quality>`, :ref:`access technology in use
+  <mobile_access_technology_in_use>`), :ref:`bandwidth <iperf3>`,
   :ref:`transferred data <iperf3>`, :ref:`restransmits <iperf3>`,
   :ref:`jitter <iperf3>`, :ref:`datagram <iperf3>`, :ref:`datagram loss
   <iperf3>`