From 410204a70d7e0680667240589c36268eb4b33a16 Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Wed, 26 Jun 2024 16:09:14 -0700 Subject: [PATCH] Formatting, whitespace, and minor fixes for Uptime Kuma hook (#885). --- NEWS | 2 + borgmatic/config/schema.yaml | 2 +- borgmatic/hooks/monitor.py | 8 ++-- borgmatic/hooks/uptimekuma.py | 10 +++-- docs/how-to/monitor-your-backups.md | 67 +++++++++++++++-------------- 5 files changed, 48 insertions(+), 41 deletions(-) diff --git a/NEWS b/NEWS index 65f73e2..806e3d8 100644 --- a/NEWS +++ b/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. diff --git a/borgmatic/config/schema.yaml b/borgmatic/config/schema.yaml index 7d4edd4..a55c638 100644 --- a/borgmatic/config/schema.yaml +++ b/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 diff --git a/borgmatic/hooks/monitor.py b/borgmatic/hooks/monitor.py index abe28c5..1b4e273 100644 --- a/borgmatic/hooks/monitor.py +++ b/borgmatic/hooks/monitor.py @@ -2,12 +2,12 @@ from enum import Enum MONITOR_HOOK_NAMES = ( 'apprise', - 'healthchecks', - 'cronitor', 'cronhub', - 'pagerduty', - 'ntfy', + 'cronitor', + 'healthchecks', 'loki', + 'ntfy', + 'pagerduty', 'uptimekuma', ) diff --git a/borgmatic/hooks/uptimekuma.py b/borgmatic/hooks/uptimekuma.py index 75731be..46fa524 100644 --- a/borgmatic/hooks/uptimekuma.py +++ b/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. - Use the given configuration filename in any log entries. - If this is a dry run, then don't actually push anything. + Make a get request to the configured Uptime Kuma push_url. Use the given configuration filename + in any log entries. 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: diff --git a/docs/how-to/monitor-your-backups.md b/docs/how-to/monitor-your-backups.md index 3786d93..0bfeb70 100644 --- a/docs/how-to/monitor-your-backups.md +++ b/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 -monitoring tool and can provide a Push monitor type to accept -HTTP `GET` requests from a service instead of contacting it -directly. +[Uptime Kuma](https://uptime.kuma.pet) is an easy-to-use, self-hosted +monitoring tool and can provide a Push monitor type to accept HTTP `GET` +requests from a service instead of contacting it directly. -Uptime Kuma allows you to see a history of monitor states and -can in turn alert via Ntfy, Gotify, Matrix, Apprise, Email, and many more. +Uptime Kuma allows you to see a history of monitor states and can in turn +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 -Uptime Kuma for successful backups and the ability to see on failures if -and when the backup started (was there a `start` beat?). +The `push_url` is provided to your from your Uptime Kuma service and +originally includes a query string—the text including and after the question +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 -for a backup is below: +Using `start`, `finish` and `fail` states means you will get two "up beats" in +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 -# borgmatic configuration. +# These are to be entered into Uptime Kuma and not into your borgmatic +# 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 -# the monitor goes into the "Pending" state +# Multiplied by Retries this gives a grace period within which the monitor +# goes into the "Pending" state. Heartbeat Retry = 360 # = 10 minutes -# For each Heartbeat Interval if the backup fails repeatedly, -# a notification is sent each time. +# For each Heartbeat Interval if the backup fails repeatedly, a notification +# 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