From f011431463acc871535f8afd663bbec6d99a1a36 Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Wed, 4 Oct 2023 19:23:53 -0700 Subject: [PATCH] Apprise hook documentation (#715). --- NEWS | 7 +- borgmatic/config/schema.yaml | 10 +-- docs/how-to/monitor-your-backups.md | 109 +++++++++++++++++++++------- setup.py | 2 +- tests/unit/hooks/test_apprise.py | 17 ++++- 5 files changed, 111 insertions(+), 34 deletions(-) diff --git a/NEWS b/NEWS index 031e2d4..c9531b0 100644 --- a/NEWS +++ b/NEWS @@ -1,10 +1,15 @@ +1.8.4.dev0 + * Add a monitoring hook for sending backup status to a variety of monitoring services via the + Apprise library. See the documentation for more information: + https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook + 1.8.3 * #665: BREAKING: Simplify logging logic as follows: Syslog verbosity is now disabled by default, but setting the "--syslog-verbosity" flag enables it regardless of whether you're at an interactive console. Additionally, "--log-file-verbosity" and "--monitoring-verbosity" now default to 1 (info about steps borgmatic is taking) instead of 0. And both syslog logging and file logging can be enabled simultaneously. - * #743: Add a monitoring hook for sending backup status and logs to to Grafana Loki. See the + * #743: Add a monitoring hook for sending backup status and logs to Grafana Loki. See the documentation for more information: https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook * #753: When "archive_name_format" is not set, filter archives using the default archive name diff --git a/borgmatic/config/schema.yaml b/borgmatic/config/schema.yaml index f8a10d6..41ce4c7 100644 --- a/borgmatic/config/schema.yaml +++ b/borgmatic/config/schema.yaml @@ -1324,12 +1324,12 @@ properties: example: "gotify://hostname/token" label: type: string - example: mastodon + example: gotify description: | - A list of Apprise services to publish to with URLs - and labels. The labels are used for logging. - A full list of services and their configuration can be found - at https://github.com/caronc/apprise/wiki. + A list of Apprise services to publish to with URLs and + labels. The labels are used for logging. A full list of + services and their configuration can be found at + https://github.com/caronc/apprise/wiki. example: - url: "kodi://user@hostname" label: kodi diff --git a/docs/how-to/monitor-your-backups.md b/docs/how-to/monitor-your-backups.md index e7f3a2e..d1081b4 100644 --- a/docs/how-to/monitor-your-backups.md +++ b/docs/how-to/monitor-your-backups.md @@ -36,28 +36,24 @@ below for how to configure this. ### Third-party monitoring services -borgmatic integrates with monitoring services like -[Healthchecks](https://healthchecks.io/), [Cronitor](https://cronitor.io), -[Cronhub](https://cronhub.io), [PagerDuty](https://www.pagerduty.com/), -[ntfy](https://ntfy.sh/), and [Grafana Loki](https://grafana.com/oss/loki/) -and pings these services whenever borgmatic runs. That way, you'll receive an -alert when something goes wrong or (for certain hooks) the service doesn't -hear from borgmatic for a configured interval. See [Healthchecks -hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#healthchecks-hook), -[Cronitor -hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook), -[Cronhub -hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook), -[PagerDuty -hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook), -[ntfy -hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#ntfy-hook), -and [Loki -hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook), -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) + +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). +See the documentation links above for configuration information. + +While these services and libraries offer different features, you probably only +need to use one of them at most. -While these services offer different features, you probably only need to use -one of them at most. ### Third-party monitoring software @@ -146,7 +142,7 @@ healthchecks: Prior to version 1.8.0 Put this option in the `hooks:` section of your configuration. -With this hook in place, borgmatic pings your Healthchecks project when a +With this configuration, borgmatic pings your Healthchecks project when a backup begins, ends, or errors, but only when any of the `create`, `prune`, `compact`, or `check` actions are run. @@ -190,7 +186,7 @@ cronitor: Prior to version 1.8.0 Put this option in the `hooks:` section of your configuration. -With this hook in place, borgmatic pings your Cronitor monitor when a backup +With this configuration, borgmatic pings your Cronitor monitor when a backup begins, ends, or errors, but only when any of the `prune`, `compact`, `create`, or `check` actions are run. Then, if the actions complete successfully or errors, borgmatic notifies Cronitor accordingly. @@ -217,7 +213,7 @@ cronhub: Prior to version 1.8.0 Put this option in the `hooks:` section of your configuration. -With this hook in place, borgmatic pings your Cronhub monitor when a backup +With this configuration, borgmatic pings your Cronhub monitor when a backup begins, ends, or errors, but only when any of the `prune`, `compact`, `create`, or `check` actions are run. Then, if the actions complete successfully or errors, borgmatic notifies Cronhub accordingly. @@ -258,7 +254,7 @@ pagerduty: Prior to version 1.8.0 Put this option in the `hooks:` section of your configuration. -With this hook in place, borgmatic creates a PagerDuty event for your service +With this configuration, borgmatic creates a PagerDuty event for your service whenever backups fail, but only when any of the `create`, `prune`, `compact`, or `check` actions are run. Note that borgmatic does not contact PagerDuty when a backup starts or when it ends without error. @@ -340,7 +336,7 @@ loki: url: http://localhost:3100/loki/api/v1/push ``` -With this hook in place, borgmatic sends its logs to your Loki instance as any +With this configuration, borgmatic sends its logs to your Loki instance as any of the `prune`, `compact`, `create`, or `check` actions are run. Then, after the actions complete, borgmatic notifies Loki of success or failure. @@ -375,6 +371,67 @@ loki: ``` +## Apprise hook + +New in version 1.8.4 +[Apprise](https://github.com/caronc/apprise) is a local notification library +that "allows you to send a notification to almost all of the most popular +[notification services](https://github.com/caronc/apprise/wiki) available to +us today such as: Telegram, Discord, Slack, Amazon SNS, Gotify, etc." + +Depending on how you installed borgmatic, it may not have come with Apprise. +For instance, if you originally [installed borgmatic with +pipx](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation), +run the following to install Apprise so borgmatic can use it: + +```bash +pipx install --editable --force borgmatic[Apprise] +``` + +Once Apprise is installed, configure borgmatic to notify one or more [Apprise +services](https://github.com/caronc/apprise/wiki). For example: + +```yaml +apprise: + services: + - url: gotify://hostname/token + label: gotify + - url: mastodons://access_key@hostname/@user + label: mastodon +``` + +With this configuration, borgmatic pings each of the configured Apprise +services when a backup begins, ends, or errors, but only when any of the +`prune`, `compact`, `create`, or `check` actions are run. + +You can optionally customize the contents of the default messages sent to +these services: + +```yaml +apprise: + services: + - url: gotify://hostname/token + label: gotify + start: + title: Ping! + body: Starting backup process. + finish: + title: Ping! + body: Backups successfully made. + fail: + title: Ping! + body: Your backups have failed. + states: + - start + - finish + - fail +``` + +See the [configuration +reference](https://torsion.org/borgmatic/docs/reference/configuration/) for +details. + + ## Scripting borgmatic To consume the output of borgmatic in other software, you can include an diff --git a/setup.py b/setup.py index 5e99f7c..bdaa710 100644 --- a/setup.py +++ b/setup.py @@ -1,6 +1,6 @@ from setuptools import find_packages, setup -VERSION = '1.8.3' +VERSION = '1.8.4.dev0' setup( diff --git a/tests/unit/hooks/test_apprise.py b/tests/unit/hooks/test_apprise.py index b11f769..446507b 100644 --- a/tests/unit/hooks/test_apprise.py +++ b/tests/unit/hooks/test_apprise.py @@ -195,7 +195,7 @@ def test_ping_monitor_pings_multiple_services(): ) -def test_ping_monitor_warning_for_no_services(): +def test_ping_monitor_logs_info_for_no_services(): flexmock(module.logger).should_receive('info').once() module.ping_monitor( @@ -206,3 +206,18 @@ def test_ping_monitor_warning_for_no_services(): monitoring_log_level=1, dry_run=False, ) + + +def test_ping_monitor_logs_warning_when_notify_fails(): + mock_apprise().should_receive('notify').and_return(False) + flexmock(module.logger).should_receive('warning').once() + + for state in borgmatic.hooks.monitor.State: + module.ping_monitor( + {'services': [{'url': f'ntfys://{TOPIC}', 'label': 'ntfys'}]}, + {}, + 'config.yaml', + state, + monitoring_log_level=1, + dry_run=False, + )