Formatting, whitespace, and minor fixes for Uptime Kuma hook (#885).

NEWS

@@ -2,6 +2,8 @@
  * #785: Add an "only_run_on" option to consistency checks so you can limit a check to running on
    particular days of the week. See the documentation for more information:
    https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/#check-days
+ * #885: Add Uptime Kuma monitoring hook. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#uptime-kuma-hook
  * #886: Fix a PagerDuty hook traceback with Python < 3.10.
  * #889: Fix the Healthchecks ping body size limit, restoring it to the documented 100,000 bytes.
 

borgmatic/config/schema.yaml

@@ -1766,7 +1766,7 @@ properties:
             an account at https://healthchecks.io (or self-host Healthchecks) if
             you'd like to use this service. See borgmatic monitoring
             documentation for details.
-    uptimekuma:
+    uptime_kuma:
         type: object
         required: ['push_url']
         additionalProperties: false

borgmatic/hooks/monitor.py

@@ -2,12 +2,12 @@ from enum import Enum
 
 MONITOR_HOOK_NAMES = (
     'apprise',
-    'healthchecks',
-    'cronitor',
     'cronhub',
-    'pagerduty',
+    'cronitor',
-    'ntfy',
+    'healthchecks',
     'loki',
+    'ntfy',
+    'pagerduty',
     'uptimekuma',
 )
 

borgmatic/hooks/uptimekuma.py

@@ -16,13 +16,14 @@ def initialize_monitor(
 
 def ping_monitor(hook_config, config, config_filename, state, monitoring_log_level, dry_run):
     '''
-    Make a get request to the configured Uptime Kuma push_url.
+    Make a get request to the configured Uptime Kuma push_url. Use the given configuration filename
-    Use the given configuration filename in any log entries.
+    in any log entries. If this is a dry run, then don't actually push anything.
-    If this is a dry run, then don't actually push anything.
     '''
     run_states = hook_config.get('states', ['start', 'finish', 'fail'])
+
     if state.name.lower() not in run_states:
         return
+
     dry_run_label = ' (dry run; not actually pushing)' if dry_run else ''
     status = 'down' if state.name.lower() == 'fail' else 'up'
     push_url = hook_config.get('push_url', 'https://example.uptime.kuma/api/push/abcd1234')
@@ -31,9 +32,12 @@ def ping_monitor(hook_config, config, config_filename, state, monitoring_log_lev
         f'{config_filename}: Pushing Uptime Kuma push_url {push_url}?{query} {dry_run_label}'
     )
     logger.debug(f'{config_filename}: Full Uptime Kuma state URL {push_url}?{query}')
+
     if dry_run:
         return
+
     logging.getLogger('urllib3').setLevel(logging.ERROR)
+
     try:
         response = requests.get(f'{push_url}?{query}')
         if not response.ok:

docs/how-to/monitor-your-backups.md

@@ -39,14 +39,14 @@ below for how to configure this.
 borgmatic integrates with these monitoring services and libraries, pinging
 them as backups happen:
 
- * [Healthchecks](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#healthchecks-hook)
- * [Cronitor](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook)
- * [Cronhub](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook)
- * [PagerDuty](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook)
- * [ntfy](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#ntfy-hook)
- * [Grafana Loki](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook)
  * [Apprise](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook)
- * [Uptime Kuma](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#uptimekuma-hook)
+ * [Cronhub](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook)
+ * [Cronitor](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook)
+ * [Grafana Loki](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook)
+ * [Healthchecks](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#healthchecks-hook)
+ * [ntfy](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#ntfy-hook)
+ * [PagerDuty](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook)
+ * [Uptime Kuma](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#uptime-kuma-hook)
 
 The idea is that you'll receive an alert when something goes wrong or when the
 service doesn't hear from borgmatic for a configured interval (if supported).
@@ -508,59 +508,60 @@ details.
 
 ## Uptime Kuma hook
 
-[Uptime Kuma](https://uptime.kuma.pet) is an easy-to-use self-hosted 
+[Uptime Kuma](https://uptime.kuma.pet) is an easy-to-use, self-hosted
-monitoring tool and can provide a Push monitor type to accept 
+monitoring tool and can provide a Push monitor type to accept HTTP `GET`
-HTTP `GET` requests from a service instead of contacting it
+requests from a service instead of contacting it directly.
-directly.
 
-Uptime Kuma allows you to see a history of monitor states and 
+Uptime Kuma allows you to see a history of monitor states and can in turn
-can in turn alert via Ntfy, Gotify, Matrix, Apprise, Email, and many more.
+alert via ntfy, Gotify, Matrix, Apprise, Email, and many more.
 
 An example configuration is shown here with all the available options:
 
 ```yaml
-uptimekuma:
+uptime_kuma:
     push_url: https://kuma.my-domain.com/api/push/abcd1234
     states:
         - start
         - finish
         - fail
 ```
-The `push_url` is provided to your from your Uptime Kuma service and 
-includes a query string; the text including and after the question mark ('?').
-Please do not include the query string in the `push_url` configuration, 
-borgmatic will add this automatically depending on the state of your backup. 
 
-Using `start`, `finish` and `fail` states means you will get two 'up beats' in 
+The `push_url` is provided to your from your Uptime Kuma service and
-Uptime Kuma for successful backups and the ability to see on failures if 
+originally includes a query string—the text including and after the question
-and when the backup started (was there a `start` beat?).
+mark (`?`). But please do not include the query string in the `push_url`
+configuration; borgmatic will add this automatically depending on the state of
+your backup. 
 
-A reasonable base-level configuration for an Uptime Kuma Monitor 
+Using `start`, `finish` and `fail` states means you will get two "up beats" in
-for a backup is below:
+Uptime Kuma for successful backups and the ability to see failures if and when
+the backup started (was there a `start` beat?).
+
+A reasonable base-level configuration for an Uptime Kuma Monitor for a backup
+is below:
 
 ```ini
-# These are to be entered into Uptime Kuma and not into your
+# These are to be entered into Uptime Kuma and not into your borgmatic
-# borgmatic configuration.
+# configuration.
 
+# Push monitors wait for the client to contact Uptime Kuma instead of Uptime
+# Kuma contacting the client. This is perfect for backup monitoring.
 Monitor Type = Push
-# Push monitors wait for the client to contact Uptime Kuma
-# instead of Uptime Kuma contacting the client.
-# This is perfect for backup monitoring.
 
 Heartbeat Interval = 90000     # = 25 hours = 1 day + 1 hour
 
-# Wait 6 times the Heartbeat Retry (below) before logging a heartbeat missed
+# Wait 6 times the Heartbeat Retry (below) before logging a heartbeat missed.
 Retries = 6
 
-# Multiplied by Retries this gives a grace period within which 
+# Multiplied by Retries this gives a grace period within which the monitor
-# the monitor goes into the "Pending" state
+# goes into the "Pending" state.
 Heartbeat Retry = 360          # = 10 minutes
 
-# For each Heartbeat Interval if the backup fails repeatedly, 
+# For each Heartbeat Interval if the backup fails repeatedly, a notification
-# a notification is sent each time.
+# is sent each time.
 Resend Notification every X times = 1
 ```
 
+
 ## Scripting borgmatic
 
 To consume the output of borgmatic in other software, you can include an