From 4750ac0d7766a8a089adf073415af0ac0d3f81d9 Mon Sep 17 00:00:00 2001 From: Paul Cuzner Date: Tue, 19 Oct 2021 13:07:02 +1300 Subject: [PATCH] mgr/prometheus: add test cases and validation using tox Focus all tests inside a tests directory, and use pytest/tox to perform validation of the overall content. tox tests also use promtool if available to provide rule checks and unittest runs. In addition to these checks a validate_rules script provides the format, and content checks against all rules - which is also called via tox (but can be run independently too) Signed-off-by: Paul Cuzner --- .../prometheus/alerts/ceph_default_alerts.yml | 58 +-- monitoring/prometheus/tests/README.md | 92 ++++ monitoring/prometheus/tests/__init__.py | 0 monitoring/prometheus/tests/requirements.txt | 2 + monitoring/prometheus/tests/settings.py | 2 + .../{alerts => tests}/test_alerts.yml | 56 +- monitoring/prometheus/tests/test_syntax.py | 42 ++ monitoring/prometheus/tests/test_unittests.py | 19 + monitoring/prometheus/tests/tox.ini | 11 + monitoring/prometheus/tests/utils.py | 12 + monitoring/prometheus/tests/validate_rules.py | 486 ++++++++++++++++++ 11 files changed, 723 insertions(+), 57 deletions(-) create mode 100644 monitoring/prometheus/tests/README.md create mode 100644 monitoring/prometheus/tests/__init__.py create mode 100644 monitoring/prometheus/tests/requirements.txt create mode 100644 monitoring/prometheus/tests/settings.py rename monitoring/prometheus/{alerts => tests}/test_alerts.yml (98%) create mode 100755 monitoring/prometheus/tests/test_syntax.py create mode 100644 monitoring/prometheus/tests/test_unittests.py create mode 100644 monitoring/prometheus/tests/tox.ini create mode 100644 monitoring/prometheus/tests/utils.py create mode 100755 monitoring/prometheus/tests/validate_rules.py diff --git a/monitoring/prometheus/alerts/ceph_default_alerts.yml b/monitoring/prometheus/alerts/ceph_default_alerts.yml index 420472d35eebf..4b9ea51ebe1d8 100644 --- a/monitoring/prometheus/alerts/ceph_default_alerts.yml +++ b/monitoring/prometheus/alerts/ceph_default_alerts.yml @@ -35,7 +35,7 @@ groups: type: ceph_default oid: 1.3.6.1.4.1.50495.15.1.2.3.1 annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#mon-down + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#mon-down description: | {{ $min := query "floor(count(ceph_mon_metadata) / 2) +1" | first | value }}Quorum requires a majority of monitors (x {{ $min }}) to be active Without quorum the cluster will become inoperable, affecting all connected clients and services. @@ -51,7 +51,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#mon-down + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#mon-down description: | {{ $down := query "count(ceph_mon_quorum_status == 0)" | first | value }}{{ $s := "" }}{{ if gt $down 1.0 }}{{ $s = "s" }}{{ end }}You have {{ $down }} monitor{{ $s }} down. Quorum is still intact, but the loss of further monitors will make your cluster inoperable. @@ -67,7 +67,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#mon-disk-crit + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#mon-disk-crit description: | The free space available to a monitor's store is critically low (<5% by default). You should increase the space available to the monitor(s). The @@ -83,7 +83,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#mon-disk-low + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#mon-disk-low description: | The space available to a monitor's store is approaching full (>70% is the default). You should increase the space available to the monitor store. The @@ -99,7 +99,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#mon-clock-skew + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#mon-clock-skew description: | The ceph monitors rely on a consistent time reference to maintain quorum and cluster consistency. This event indicates that at least @@ -144,7 +144,7 @@ groups: type: ceph_default oid: 1.3.6.1.4.1.50495.15.1.2.4.2 annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#osd-down + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#osd-down description: | {{ $num := query "count(ceph_osd_up == 0)" | first | value }}{{ $s := "" }}{{ if gt $num 1.0 }}{{ $s = "s" }}{{ end }}{{ $num }} OSD{{ $s }} down for over 5mins. @@ -161,7 +161,7 @@ groups: type: ceph_default oid: 1.3.6.1.4.1.50495.15.1.2.4.3 annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#osd-nearfull + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#osd-nearfull description: | One or more OSDs have reached their NEARFULL threshold @@ -174,7 +174,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#osd-full + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#osd-full description: | An OSD has reached it's full threshold. Writes from all pools that share the affected OSD will be blocked. @@ -187,7 +187,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#osd-backfillfull + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#osd-backfillfull description: | An OSD has reached it's BACKFILL FULL threshold. This will prevent rebalance operations completing for some pools. Check the current capacity utilisation with 'ceph df' @@ -200,7 +200,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#osd-too-many-repairs + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#osd-too-many-repairs description: | Reads from an OSD have used a secondary PG to return data to the client, indicating a potential failing disk. @@ -231,7 +231,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#bluestore-disk-size-mismatch + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#bluestore-disk-size-mismatch description: | One or more OSDs have an internal inconsistency between the size of the physical device and it's metadata. This could lead to the OSD(s) crashing in future. You should redeploy the effected OSDs. @@ -242,7 +242,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#id2 + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#id2 description: | The device health module has determined that one or more devices will fail soon. To review the device states use 'ceph device ls'. To show a specific @@ -257,7 +257,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#device-health-toomany + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#device-health-toomany description: | The device health module has determined that the number of devices predicted to fail can not be remediated automatically, since it would take too many osd's out of @@ -270,7 +270,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#device-health-in-use + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#device-health-in-use description: | The device health module has determined that one or more devices will fail soon, but the normal process of relocating the data on the device to other @@ -291,7 +291,7 @@ groups: type: ceph_default oid: 1.3.6.1.4.1.50495.15.1.2.4.4 annotations: - documentation: https://docs.ceph.com/en/latest/rados/troubleshooting/troubleshooting-osd/#flapping-osds + documentation: https://docs.ceph.com/en/latest/rados/troubleshooting/troubleshooting-osd#flapping-osds description: > OSD {{ $labels.ceph_daemon }} on {{ $labels.hostname }} was marked down and back up at {{ $value | humanize }} times once a @@ -306,7 +306,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#bluestore-spurious-read-errors + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#bluestore-spurious-read-errors description: > An OSD has encountered read errors, but the OSD has recovered by retrying the reads. This may indicate an issue with the Hardware or Kernel. @@ -338,7 +338,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/cephfs/health-messages/#cephfs-health-messages + documentation: https://docs.ceph.com/en/latest/cephfs/health-messages#cephfs-health-messages description: > The filesystems metadata has been corrupted. Data access may be blocked. @@ -352,7 +352,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/cephfs/health-messages/#cephfs-health-messages + documentation: https://docs.ceph.com/en/latest/cephfs/health-messages#cephfs-health-messages description: > The filesystem has switched to READ ONLY due to an unexpected write error, when writing to the metadata pool @@ -369,7 +369,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#recent-mgr-module-crash + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#recent-mgr-module-crash description: > One or more mgr modules have crashed and are yet to be acknowledged by the administrator. A crashed module may impact functionality within the cluster. Use the 'ceph crash' commands to @@ -423,7 +423,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-damaged + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-damaged description: > During data consistency checks (scrub), at least one PG has been flagged as being damaged or inconsistent. @@ -438,7 +438,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-recovery-full + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-recovery-full description: > Data redundancy may be reduced, or is at risk, since one or more OSDs are at or above their 'full' threshold. Add more capacity to the cluster, or delete unwanted data. @@ -450,7 +450,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-availability + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-availability description: > Data availability is reduced impacting the clusters abilty to service I/O to some data. One or more placement groups (PGs) are in a state that blocks IO. @@ -461,7 +461,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-backfill-full + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-backfill-full description: > Data redundancy may be at risk due to lack of free space within the cluster. One or more OSDs have breached their 'backfillfull' threshold. Add more capacity, or delete unwanted data. @@ -472,7 +472,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-not-scrubbed + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-not-scrubbed description: | One or more PGs have not been scrubbed recently. The scrub process is a data integrity feature, protectng against bit-rot. It checks that objects and their metadata (size and @@ -488,7 +488,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-not-deep-scrubbed + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-not-deep-scrubbed description: | One or more PGs have not been deep scrubbed recently. Deep scrub is a data integrity feature, protectng against bit-rot. It compares the contents of objects and their @@ -627,7 +627,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pool-full + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pool-full description: | A pool has reached it's MAX quota, or the OSDs supporting the pool have reached their FULL threshold. Until this is resolved, writes to @@ -663,7 +663,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#slow-ops + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#slow-ops description: > {{ $value }} OSD requests are taking too long to process (osd_op_complaint_time exceeded) # cephadm alerts @@ -699,7 +699,7 @@ groups: severity: warning type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/cephadm/operations/#cephadm-paused + documentation: https://docs.ceph.com/en/latest/cephadm/operations#cephadm-paused description: > Cluster management has been paused manually. This will prevent the orchestrator from service management and reconciliation. If this is @@ -731,7 +731,7 @@ groups: severity: critical type: ceph_default annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#object-unfound + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#object-unfound description: | A version of a RADOS object can not be found, even though all OSDs are up. I/O requests for this object from clients will block (hang). Resolving this issue may diff --git a/monitoring/prometheus/tests/README.md b/monitoring/prometheus/tests/README.md new file mode 100644 index 0000000000000..cf95fa6368d52 --- /dev/null +++ b/monitoring/prometheus/tests/README.md @@ -0,0 +1,92 @@ + +## Alert Rule Standards + +The alert rules should adhere to the following principles +- each alert must have a unique name +- each alert should define a common structure + - labels : must contain severity and type + - annotations : must provide description + - expr : must define the promql expression + - alert : defines the alert name +- alerts that have a corresponding section within docs.ceph.com must include a + documentation field in the annotations section +- critical alerts should declare an oid in the labels section +- critical alerts should have a corresponding entry in the Ceph MIB + +  +## Testing Prometheus Rules +Once you have updated the `ceph_default_alerts.yml` file, you should use the +`validate_rules.py` script directly, or via `tox` to ensure the format of any update +or change aligns to our rule structure guidelines. The validate_rules.py script will +process the rules and look for any configuration anomalies and output a report if +problems are detected. + +Here's an example run, to illustrate the format and the kinds of issues detected. + +``` +[paul@myhost tests]$ ./validate_rules.py + +Checking rule groups + cluster health : .. + mon : E.W.. + osd : E...W......W.E.. + mds : WW + mgr : WW + pgs : ..WWWW.. + nodes : .EEEE + pools : EEEW. + healthchecks : . + cephadm : WW. + prometheus : W + rados : W + +Summary + +Rule file : ../alerts/ceph_default_alerts.yml +Unit Test file : test_alerts.yml + +Rule groups processed : 12 +Rules processed : 51 +Rule errors : 10 +Rule warnings : 16 +Rule name duplicates : 0 +Unit tests missing : 4 + +Problem Report + + Group Severity Alert Name Problem Description + ----- -------- ---------- ------------------- + cephadm Warning Cluster upgrade has failed critical level alert is missing an SNMP oid entry + cephadm Warning A daemon managed by cephadm is down critical level alert is missing an SNMP oid entry + mds Warning Ceph Filesystem damage detected critical level alert is missing an SNMP oid entry + mds Warning Ceph Filesystem switched to READ ONLY critical level alert is missing an SNMP oid entry + mgr Warning mgr module failure critical level alert is missing an SNMP oid entry + mgr Warning mgr prometheus module is not active critical level alert is missing an SNMP oid entry + mon Error Monitor down, quorum is at risk documentation link error: #mon-downwah not found on the page + mon Warning Ceph mon disk space critically low critical level alert is missing an SNMP oid entry + nodes Error network packets dropped invalid alert structure. Missing field: for + nodes Error network packet errors invalid alert structure. Missing field: for + nodes Error storage filling up invalid alert structure. Missing field: for + nodes Error MTU Mismatch invalid alert structure. Missing field: for + osd Error 10% OSDs down invalid alert structure. Missing field: for + osd Error Flapping OSD invalid alert structure. Missing field: for + osd Warning OSD Full critical level alert is missing an SNMP oid entry + osd Warning Too many devices predicted to fail critical level alert is missing an SNMP oid entry + pgs Warning Placement Group (PG) damaged critical level alert is missing an SNMP oid entry + pgs Warning Recovery at risk, cluster too full critical level alert is missing an SNMP oid entry + pgs Warning I/O blocked to some data critical level alert is missing an SNMP oid entry + pgs Warning Cluster too full, automatic data recovery impaired critical level alert is missing an SNMP oid entry + pools Error pool full invalid alert structure. Missing field: for + pools Error pool filling up (growth forecast) invalid alert structure. Missing field: for + pools Error Ceph pool is too full for recovery/rebalance invalid alert structure. Missing field: for + pools Warning Ceph pool is full - writes blocked critical level alert is missing an SNMP oid entry + prometheus Warning Scrape job is missing critical level alert is missing an SNMP oid entry + rados Warning Data not found/missing critical level alert is missing an SNMP oid entry + +Unit tests are incomplete. Tests missing for the following alerts; + - Placement Group (PG) damaged + - OSD Full + - storage filling up + - pool filling up (growth forecast) + +``` diff --git a/monitoring/prometheus/tests/__init__.py b/monitoring/prometheus/tests/__init__.py new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/monitoring/prometheus/tests/requirements.txt b/monitoring/prometheus/tests/requirements.txt new file mode 100644 index 0000000000000..bd25cccf86d77 --- /dev/null +++ b/monitoring/prometheus/tests/requirements.txt @@ -0,0 +1,2 @@ +pyyaml +bs4 \ No newline at end of file diff --git a/monitoring/prometheus/tests/settings.py b/monitoring/prometheus/tests/settings.py new file mode 100644 index 0000000000000..c54f141a3edf6 --- /dev/null +++ b/monitoring/prometheus/tests/settings.py @@ -0,0 +1,2 @@ +ALERTS_FILE = '../alerts/ceph_default_alerts.yml' +UNIT_TESTS_FILE = 'test_alerts.yml' \ No newline at end of file diff --git a/monitoring/prometheus/alerts/test_alerts.yml b/monitoring/prometheus/tests/test_alerts.yml similarity index 98% rename from monitoring/prometheus/alerts/test_alerts.yml rename to monitoring/prometheus/tests/test_alerts.yml index 1e855c0902b03..ab423c983d0c7 100644 --- a/monitoring/prometheus/alerts/test_alerts.yml +++ b/monitoring/prometheus/tests/test_alerts.yml @@ -1,5 +1,5 @@ rule_files: - - ceph_default_alerts.yml + - ../alerts/ceph_default_alerts.yml evaluation_interval: 5m tests: # health error @@ -351,7 +351,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/troubleshooting/troubleshooting-osd/#flapping-osds + documentation: https://docs.ceph.com/en/latest/rados/troubleshooting/troubleshooting-osd#flapping-osds description: > OSD osd.0 on ceph was marked down and back up at 20.1 times once a minute for 5 minutes. @@ -795,7 +795,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#slow-ops + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#slow-ops description: > 1 OSD requests are taking too long to process (osd_op_complaint_time exceeded) @@ -873,7 +873,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/cephadm/operations/#cephadm-paused + documentation: https://docs.ceph.com/en/latest/cephadm/operations#cephadm-paused description: > Cluster management has been paused manually. This will prevent the orchestrator from service management and reconciliation. If this is @@ -900,7 +900,7 @@ tests: severity: critical type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/cephfs/health-messages/#cephfs-health-messages + documentation: https://docs.ceph.com/en/latest/cephfs/health-messages#cephfs-health-messages description: > The filesystems metadata has been corrupted. Data access may be blocked. @@ -928,7 +928,7 @@ tests: severity: critical type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/cephfs/health-messages/#cephfs-health-messages + documentation: https://docs.ceph.com/en/latest/cephfs/health-messages#cephfs-health-messages description: > The filesystem has switched to READ ONLY due to an unexpected write error, when writing to the metadata pool @@ -988,7 +988,7 @@ tests: severity: critical type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#recent-mgr-module-crash + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#recent-mgr-module-crash description: > One or more mgr modules have crashed and are yet to be acknowledged by the administrator. A crashed module may impact functionality within the cluster. Use the 'ceph crash' commands to @@ -1017,7 +1017,7 @@ tests: severity: critical type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#mon-disk-crit + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#mon-disk-crit description: | The free space available to a monitor's store is critically low (<5% by default). You should increase the space available to the monitor(s). The @@ -1046,7 +1046,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#mon-disk-low + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#mon-disk-low description: | The space available to a monitor's store is approaching full (>70% is the default). You should increase the space available to the monitor store. The @@ -1073,7 +1073,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#mon-clock-skew + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#mon-clock-skew description: | The ceph monitors rely on a consistent time reference to maintain quorum and cluster consistency. This event indicates that at least @@ -1117,7 +1117,7 @@ tests: type: ceph_default oid: 1.3.6.1.4.1.50495.15.1.2.3.1 exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#mon-down + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#mon-down description: | Quorum requires a majority of monitors (x 2) to be active Without quorum the cluster will become inoperable, affecting all connected clients and services. @@ -1163,7 +1163,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#mon-down + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#mon-down description: | You have 1 monitor down. Quorum is still intact, but the loss of further monitors will make your cluster inoperable. @@ -1192,7 +1192,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#id2 + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#id2 description: | The device health module has determined that one or more devices will fail soon. To review the device states use 'ceph device ls'. To show a specific @@ -1221,7 +1221,7 @@ tests: severity: critical type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#device-health-toomany + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#device-health-toomany description: | The device health module has determined that the number of devices predicted to fail can not be remediated automatically, since it would take too many osd's out of @@ -1248,7 +1248,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#device-health-in-use + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#device-health-in-use description: | The device health module has determined that one or more devices will fail soon, but the normal process of relocating the data on the device to other @@ -1355,7 +1355,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#bluestore-disk-size-mismatch + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#bluestore-disk-size-mismatch description: | One or more OSDs have an internal inconsistency between the size of the physical device and it's metadata. This could lead to the OSD(s) crashing in future. You should redeploy the effected OSDs. @@ -1380,7 +1380,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#bluestore-spurious-read-errors + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#bluestore-spurious-read-errors description: > An OSD has encountered read errors, but the OSD has recovered by retrying the reads. This may indicate an issue with the Hardware or Kernel. @@ -1418,7 +1418,7 @@ tests: type: ceph_default oid: 1.3.6.1.4.1.50495.15.1.2.4.2 exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#osd-down + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#osd-down description: | 1 OSD down for over 5mins. @@ -1446,7 +1446,7 @@ tests: type: ceph_default oid: 1.3.6.1.4.1.50495.15.1.2.4.3 exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#osd-nearfull + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#osd-nearfull description: | One or more OSDs have reached their NEARFULL threshold @@ -1473,7 +1473,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#osd-backfillfull + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#osd-backfillfull description: | An OSD has reached it's BACKFILL FULL threshold. This will prevent rebalance operations completing for some pools. Check the current capacity utilisation with 'ceph df' @@ -1500,7 +1500,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#osd-too-many-repairs + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#osd-too-many-repairs description: | Reads from an OSD have used a secondary PG to return data to the client, indicating a potential failing disk. @@ -1552,7 +1552,7 @@ tests: severity: critical type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pool-full + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pool-full description: | A pool has reached it's MAX quota, or the OSDs supporting the pool have reached their FULL threshold. Until this is resolved, writes to @@ -1616,7 +1616,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-not-scrubbed + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-not-scrubbed description: | One or more PGs have not been scrubbed recently. The scrub process is a data integrity feature, protectng against bit-rot. It checks that objects and their metadata (size and @@ -1646,7 +1646,7 @@ tests: severity: critical type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-recovery-full + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-recovery-full description: > Data redundancy may be reduced, or is at risk, since one or more OSDs are at or above their 'full' threshold. Add more capacity to the cluster, or delete unwanted data. @@ -1671,7 +1671,7 @@ tests: severity: critical type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-backfill-full + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-backfill-full description: > Data redundancy may be at risk due to lack of free space within the cluster. One or more OSDs have breached their 'backfillfull' threshold. Add more capacity, or delete unwanted data. @@ -1704,7 +1704,7 @@ tests: severity: critical type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-availability + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-availability description: > Data availability is reduced impacting the clusters abilty to service I/O to some data. One or more placement groups (PGs) are in a state that blocks IO. @@ -1729,7 +1729,7 @@ tests: severity: warning type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#pg-not-deep-scrubbed + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#pg-not-deep-scrubbed description: | One or more PGs have not been deep scrubbed recently. Deep scrub is a data integrity feature, protectng against bit-rot. It compares the contents of objects and their @@ -1799,7 +1799,7 @@ tests: severity: critical type: ceph_default exp_annotations: - documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks/#object-unfound + documentation: https://docs.ceph.com/en/latest/rados/operations/health-checks#object-unfound description: | A version of a RADOS object can not be found, even though all OSDs are up. I/O requests for this object from clients will block (hang). Resolving this issue may diff --git a/monitoring/prometheus/tests/test_syntax.py b/monitoring/prometheus/tests/test_syntax.py new file mode 100755 index 0000000000000..966d768bdcd07 --- /dev/null +++ b/monitoring/prometheus/tests/test_syntax.py @@ -0,0 +1,42 @@ +import pytest +import os +import yaml +from .utils import promtool_available, call +from .settings import ALERTS_FILE, UNIT_TESTS_FILE + + +def load_yaml(file_name): + yaml_data = None + with open(file_name, 'r') as alert_file: + raw = alert_file.read() + try: + yaml_data = yaml.safe_load(raw) + except yaml.YAMLError as e: + pass + + return yaml_data + + +def test_alerts_present(): + assert os.path.exists(ALERTS_FILE), f"{ALERTS_FILE} not found" + + +def test_unittests_present(): + assert os.path.exists(UNIT_TESTS_FILE), f"{UNIT_TESTS_FILE} not found" + + +@pytest.mark.skipif(not os.path.exists(ALERTS_FILE), reason=f"{ALERTS_FILE} missing") +def test_rules_format(): + assert load_yaml(ALERTS_FILE) + + +@pytest.mark.skipif(not os.path.exists(UNIT_TESTS_FILE), reason=f"{UNIT_TESTS_FILE} missing") +def test_unittests_format(): + assert load_yaml(UNIT_TESTS_FILE) + + +@pytest.mark.skipif(not promtool_available(), reason="promtool is not installed. Unable to check syntax") +def test_rule_syntax(): + completion = call(f"promtool check rules {ALERTS_FILE}") + assert completion.returncode == 0 + assert b"SUCCESS" in completion.stdout diff --git a/monitoring/prometheus/tests/test_unittests.py b/monitoring/prometheus/tests/test_unittests.py new file mode 100644 index 0000000000000..4cfb2b6008f4c --- /dev/null +++ b/monitoring/prometheus/tests/test_unittests.py @@ -0,0 +1,19 @@ +import pytest +import os +from .utils import promtool_available, call +from .settings import ALERTS_FILE, UNIT_TESTS_FILE + + +def test_alerts_present(): + assert os.path.exists(ALERTS_FILE), f"{ALERTS_FILE} not found" + + +def test_unittests_present(): + assert os.path.exists(UNIT_TESTS_FILE), f"{UNIT_TESTS_FILE} not found" + + +@pytest.mark.skipif(not promtool_available(), reason="promtool is not installed. Unable to run unit tests") +def test_run_unittests(): + completion = call(f"promtool test rules {UNIT_TESTS_FILE}") + assert completion.returncode == 0 + assert b"SUCCESS" in completion.stdout diff --git a/monitoring/prometheus/tests/tox.ini b/monitoring/prometheus/tests/tox.ini new file mode 100644 index 0000000000000..8adde12f51758 --- /dev/null +++ b/monitoring/prometheus/tests/tox.ini @@ -0,0 +1,11 @@ +[tox] +envlist = py36 +skipsdist = true + +[testenv] +deps = + -rrequirements.txt + pytest +commands = + pytest -rA test_syntax.py test_unittests.py + ./validate_rules.py diff --git a/monitoring/prometheus/tests/utils.py b/monitoring/prometheus/tests/utils.py new file mode 100644 index 0000000000000..8429244472d1f --- /dev/null +++ b/monitoring/prometheus/tests/utils.py @@ -0,0 +1,12 @@ +import pytest +import shutil +import subprocess + + +def promtool_available() -> bool: + return shutil.which('promtool') is not None + + +def call(cmd): + completion = subprocess.run(cmd.split(), stdout=subprocess.PIPE) + return completion diff --git a/monitoring/prometheus/tests/validate_rules.py b/monitoring/prometheus/tests/validate_rules.py new file mode 100755 index 0000000000000..b424533242903 --- /dev/null +++ b/monitoring/prometheus/tests/validate_rules.py @@ -0,0 +1,486 @@ +#!/usr/bin/python3 -u +# +# Check the Prometheus rules for format, and integration +# with the unit tests. This script has the following exit +# codes: +# 0 .. Everything worked +# 4 .. rule problems or missing unit tests +# 8 .. Missing fields in YAML +# 12 .. Invalid YAML - unable to load +# 16 .. Missing input files + +# TODO: logging for debug + +import re +import os +import sys +import yaml +from bs4 import BeautifulSoup +from typing import List, Any, Dict, Set, Optional, Tuple + +import urllib.request +import urllib.error +from urllib.parse import urlparse + +DOCLINK_NAME = 'documentation' +DEFAULT_RULES_FILENAME = '../alerts/ceph_default_alerts.yml' +DEFAULT_TEST_FILENAME = 'test_alerts.yml' + + +def read_file(file_name: str) -> Tuple[str, str]: + try: + with open(file_name, 'r') as input_file: + raw_data = input_file.read() + except OSError: + return '', f"Unable to open {file_name}" + + return raw_data, '' + + +def load_yaml(file_name: str) -> Tuple[Dict[str, Any], str]: + data = {} + errs = '' + + raw_data, err = read_file(file_name) + if not err: + + try: + data = yaml.safe_load(raw_data) + except yaml.YAMLError as e: + errs = f"filename '{file_name} is not a valid YAML file" + + return data, errs + + +class HTMLCache: + def __init__(self) -> None: + self.cache: Dict[str, Tuple[int, str]] = {} + + def fetch(self, url_str: str) -> None: + parsed = urlparse(url_str) + url = f"{parsed.scheme}://{parsed.netloc}{parsed.path}" + + if url in self.cache: + return self.cache[url] + + req = urllib.request.Request(url) + try: + r = urllib.request.urlopen(req) + except urllib.error.HTTPError as e: + self.cache[url] = e.code, e.reason + return self.cache[url] + except urllib.error.URLError as e: + self.cache[url] = 400, e.reason + return self.cache[url] + + if r.status == 200: + html = r.read().decode('utf-8') + self.cache[url] = 200, html + return self.cache[url] + + self.cache[url] = r.status, r.reason + return r.status, r.reason + + @property + def cached_pages(self) -> List[str]: + return self.cache.keys() + + @property + def cached_pages_total(self) -> int: + return len(self.cache.keys()) + +class PrometheusRule: + expected_attrs = [ + 'alert', + 'expr', + 'for', + 'labels', + 'annotations' + ] + + def __init__(self, rule_group, rule_data: Dict[str, Any]): + + assert 'alert' in rule_data + self.group: RuleGroup = rule_group + self.name = rule_data.get('alert') + self.rule = rule_data + self.errors: List[str] = [] + self.warnings: List[str] = [] + + self.validate() + + def _check_alert_name(self): + pass + + def _check_structure(self): + rule_attrs = self.rule.keys() + missing_attrs = [a for a in PrometheusRule.expected_attrs if a not in rule_attrs] + + if missing_attrs: + self.errors.append( + f"invalid alert structure. Missing field{'s' if len(missing_attrs) > 1 else ''}" + f": {','.join(missing_attrs)}") + + def _check_labels(self): + for rqd in ['severity', 'type']: + if rqd not in self.rule.get('labels', ''): + self.errors.append(f"rule is missing {rqd} label definition") + + def _check_annotations(self): + for rqd in ['description']: + if rqd not in self.rule.get('annotations', ''): + self.errors.append(f"rule is missing {rqd} annotation definition") + + def _check_doclink(self): + annotations = self.rule.get('annotations', {}) + doclink = annotations.get(DOCLINK_NAME, '') + + if doclink: + url = urlparse(doclink) + status, content = self.group.fetch_html_page(doclink) + if status == 200: + if url.fragment: + soup = BeautifulSoup(content, 'html.parser') + if not soup.find(id=url.fragment): + self.errors.append(f"documentation link error: {url.fragment} anchor not found on the page") + else: + # catch all + self.errors.append(f"documentation link error: {status} {content}") + + def _check_snmp(self): + labels = self.rule.get('labels', {}) + oid = labels.get('oid', '') + if labels.get('severity', '') == 'critical' and not oid: + self.warnings.append("critical level alert is missing an SNMP oid entry") + if oid and not re.search('^1.3.6.1.4.1.50495.15.1.2.\\d+.\\d+$', oid): + self.errors.append("invalid OID provided") + + def validate(self): + self._check_alert_name() + self._check_structure() + self._check_labels() + self._check_annotations() + self._check_doclink() + self._check_snmp() + char = '.' + + if self.errors: + char = 'E' + self.group.update('error', self.name) + elif self.warnings: + char = 'W' + self.group.update('warning', self.name) + + sys.stdout.write(char) + + +class RuleGroup: + + def __init__(self, rule_file, group_name: str, group_name_width: int): + self.rule_file: RuleFile = rule_file + self.group_name = group_name + self.rules: Dict[str, PrometheusRule] = {} + self.problems = { + "error": [], + "warning": [], + } + + sys.stdout.write(f"\n\t{group_name:<{group_name_width}} : ") + + def add_rule(self, rule_data:Dict[str, Any]): + alert_name = rule_data.get('alert') + self.rules[alert_name] = PrometheusRule(self, rule_data) + + def update(self, problem_type:str, alert_name:str): + assert problem_type in ['error', 'warning'] + + self.problems[problem_type].append(alert_name) + self.rule_file.update(self.group_name) + + def fetch_html_page(self, url): + return self.rule_file.fetch_html_page(url) + + @property + def error_count(self): + return len(self.problems['error']) + + def warning_count(self): + return len(self.problems['warning']) + + @property + def count(self): + return len(self.rules) + + +class RuleFile: + + def __init__(self, parent, file_name, rules): + self.parent = parent + self.file_name = file_name + self.rules: Dict[str, Any] = rules + self.problems: Set[str] = set() + self.group: Dict[str, RuleGroup] = {} + self.alert_names_seen: Set[str] = set() + self.duplicate_alert_names:List[str] = [] + self.html_cache = HTMLCache() + + assert 'groups' in self.rules + self.max_group_name_width = self.get_max_group_name() + self.load_groups() + + def update(self, group_name): + self.problems.add(group_name) + self.parent.mark_invalid() + + def fetch_html_page(self, url): + return self.html_cache.fetch(url) + + @property + def group_count(self): + return len(self.rules['groups']) + + @property + def rule_count(self): + rule_count = 0 + for group_name, rule_group in self.group.items(): + rule_count += rule_group.count + return rule_count + + @property + def group_names(self): + return self.group.keys() + + @property + def problem_count(self): + return len(self.problems) + + def get_max_group_name(self): + group_name_list = [] + for group in self.rules.get('groups'): + group_name_list.append(group['name']) + return max([len(g) for g in group_name_list]) + + def load_groups(self): + sys.stdout.write("\nChecking rule groups") + for group in self.rules.get('groups'): + group_name = group['name'] + rules = group['rules'] + self.group[group_name] = RuleGroup(self, group_name, self.max_group_name_width) + for rule_data in rules: + if 'alert' in rule_data: + alert_name = rule_data.get('alert') + if alert_name in self.alert_names_seen: + self.duplicate_alert_names.append(alert_name) + else: + self.alert_names_seen.add(alert_name) + self.group[group_name].add_rule(rule_data) + else: + # skipped recording rule + pass + + def error_report(self): + def max_width(item_list: List[str]) -> int: + return max([len(i) for i in item_list]) + + if not self.problems and not self.duplicate_alert_names: + print("\nNo problems detected in rule file") + return + + print("\nProblem Report\n") + + group_width = max_width(self.problems) + alert_names = set() + for g in self.problems: + group = self.group[g] + alert_names.update(group.problems.get('error', [])) + alert_names.update(group.problems.get('warning', [])) + alert_width = max_width(alert_names) + + template = " {group:<{group_width}} {severity:<8} {alert_name:<{alert_width}} {description}" + + print(template.format( + group="Group", + group_width=group_width, + severity="Severity", + alert_name="Alert Name", + alert_width=alert_width, + description="Problem Description")) + + print(template.format( + group="-----", + group_width=group_width, + severity="--------", + alert_name="----------", + alert_width=alert_width, + description="-------------------")) + + for group_name in sorted(self.problems): + group = self.group[group_name] + rules = group.rules + for alert_name in group.problems.get('error', []): + for desc in rules[alert_name].errors: + print(template.format( + group=group_name, + group_width=group_width, + severity="Error", + alert_name=alert_name, + alert_width=alert_width, + description=desc)) + for alert_name in group.problems.get('warning', []): + for desc in rules[alert_name].warnings: + print(template.format( + group=group_name, + group_width=group_width, + severity="Warning", + alert_name=alert_name, + alert_width=alert_width, + description=desc)) + if self.duplicate_alert_names: + print("Duplicate alert names detected:") + for a in self.duplicate_alert_names: + print(f" - {a}") + + +class UnitTests: + expected_attrs = [ + 'rule_files', + 'tests', + 'evaluation_interval' + ] + def __init__(self, filename): + self.filename = filename + self.unit_test_data: Dict[str, Any] = {} + self.alert_names_seen: Set[str] = set() + self.problems: List[str] = [] + self.load() + + def load(self): + self.unit_test_data, errs = load_yaml(self.filename) + if errs: + print(f"\n\nError in unit tests file: {errs}") + sys.exit(12) + + missing_attr = [a for a in UnitTests.expected_attrs if a not in self.unit_test_data.keys()] + if missing_attr: + print(f"\nMissing attributes in unit tests: {','.join(missing_attr)}") + sys.exit(8) + + def _check_alert_names(self, alert_names: List[str]): + alerts_tested: Set[str] = set() + for t in self.unit_test_data.get('tests'): + test_cases = t.get('alert_rule_test', []) + if not test_cases: + continue + for case in test_cases: + alertname = case.get('alertname', '') + if alertname: + alerts_tested.add(alertname) + + alerts_defined = set(alert_names) + self.problems = list(alerts_defined.difference(alerts_tested)) + + def process(self, defined_alert_names: List[str]): + self._check_alert_names(defined_alert_names) + + def error_report(self) -> None: + + if not self.problems: + print("\nNo problems detected in unit tests file") + return + + print("\nUnit tests are incomplete. Tests missing for the following alerts;") + for p in self.problems: + print(f" - {p}") + +class RuleChecker: + + def __init__(self, rules_filename: str = None, test_filename: str = None): + self.rules_filename = rules_filename or DEFAULT_RULES_FILENAME + self.test_filename = test_filename or DEFAULT_TEST_FILENAME + self.rule_file: Optional[RuleFile] = None + self.unit_tests: Optional[UnitTests] = None + self.rule_file_problems: bool = False + self.errors = {} + self.warnings = {} + self.error_count = 0 + self.warning_count = 0 + + @property + def status(self): + if self.rule_file_problems or self.unit_tests.problems: + return 4 + + return 0 + + def mark_invalid(self): + self.rule_file_problems = True + + def summarise_rule_file(self): + for group_name in self.rule_file.problems: + group = self.rule_file.group[group_name] + self.error_count += len(group.problems['error']) + self.warning_count += len(group.problems['warning']) + + def ready(self): + errs: List[str] = [] + ready_state = True + if not os.path.exists(self.rules_filename): + errs.append(f"rule file '{self.rules_filename}' not found") + ready_state = False + + if not os.path.exists(self.test_filename): + errs.append(f"test file '{self.test_filename}' not found") + ready_state = False + + return ready_state, errs + + def run(self): + + ready, errs = self.ready() + if not ready: + print("Unable to start:") + for e in errs: + print(f"- {e}") + sys.exit(16) + + rules, errs = load_yaml(self.rules_filename) + if errs: + print(errs) + sys.exit(12) + + self.rule_file = RuleFile(self, self.rules_filename, rules) + self.summarise_rule_file() + + self.unit_tests = UnitTests(self.test_filename) + self.unit_tests.process(self.rule_file.alert_names_seen) + + def error_report(self): + print("\n\nSummary\n") + print(f"Rule file : {self.rules_filename}") + print(f"Unit Test file : {self.test_filename}") + print(f"\nRule groups processed : {self.rule_file.group_count:>3}") + print(f"Rules processed : {self.rule_file.rule_count:>3}") + print(f"Rule errors : {self.error_count:>3}") + print(f"Rule warnings : {self.warning_count:>3}") + print(f"Rule name duplicates : {len(self.rule_file.duplicate_alert_names):>3}") + print(f"Unit tests missing : {len(self.unit_tests.problems):>3}") + + if self.rule_file_problems: + self.rule_file.error_report() + if self.unit_tests.problems: + self.unit_tests.error_report() + + +def main(): + checker = RuleChecker() + + checker.run() + if checker.status > 0: + checker.error_report() + print() + + sys.exit(checker.status) + + +if __name__ == '__main__': + main() -- 2.39.5