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

This commit is contained in:
Dan Helfman 2024-06-26 16:09:14 -07:00
parent 4a0c167c1c
commit 410204a70d
5 changed files with 48 additions and 41 deletions

2
NEWS
View file

@ -2,6 +2,8 @@
* #785: Add an "only_run_on" option to consistency checks so you can limit a check to running on * #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: 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 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. * #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. * #889: Fix the Healthchecks ping body size limit, restoring it to the documented 100,000 bytes.

View file

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

View file

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

View file

@ -16,13 +16,14 @@ def initialize_monitor(
def ping_monitor(hook_config, config, config_filename, state, monitoring_log_level, dry_run): 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']) run_states = hook_config.get('states', ['start', 'finish', 'fail'])
if state.name.lower() not in run_states: if state.name.lower() not in run_states:
return return
dry_run_label = ' (dry run; not actually pushing)' if dry_run else '' dry_run_label = ' (dry run; not actually pushing)' if dry_run else ''
status = 'down' if state.name.lower() == 'fail' else 'up' status = 'down' if state.name.lower() == 'fail' else 'up'
push_url = hook_config.get('push_url', 'https://example.uptime.kuma/api/push/abcd1234') 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}' 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}') logger.debug(f'{config_filename}: Full Uptime Kuma state URL {push_url}?{query}')
if dry_run: if dry_run:
return return
logging.getLogger('urllib3').setLevel(logging.ERROR) logging.getLogger('urllib3').setLevel(logging.ERROR)
try: try:
response = requests.get(f'{push_url}?{query}') response = requests.get(f'{push_url}?{query}')
if not response.ok: if not response.ok:

View file

@ -39,14 +39,14 @@ below for how to configure this.
borgmatic integrates with these monitoring services and libraries, pinging borgmatic integrates with these monitoring services and libraries, pinging
them as backups happen: 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) * [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 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). service doesn't hear from borgmatic for a configured interval (if supported).
@ -508,59 +508,60 @@ details.
## Uptime Kuma hook ## 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: An example configuration is shown here with all the available options:
```yaml ```yaml
uptimekuma: uptime_kuma:
push_url: https://kuma.my-domain.com/api/push/abcd1234 push_url: https://kuma.my-domain.com/api/push/abcd1234
states: states:
- start - start
- finish - finish
- fail - 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 ```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 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 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 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 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 Resend Notification every X times = 1
``` ```
## Scripting borgmatic ## Scripting borgmatic
To consume the output of borgmatic in other software, you can include an To consume the output of borgmatic in other software, you can include an