Apprise hook documentation (#715).

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

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
+                    A list of Apprise services to publish to with URLs and
-                    and labels. The labels are used for logging.
+                    labels. The labels are used for logging. A full list of
-                    A full list of services and their configuration can be found
+                    services and their configuration can be found at
-                    at https://github.com/caronc/apprise/wiki.
+                    https://github.com/caronc/apprise/wiki.
                 example:
                     - url: "kodi://user@hostname"
                       label: kodi

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
+borgmatic integrates with these monitoring services and libraries, pinging
-[Healthchecks](https://healthchecks.io/), [Cronitor](https://cronitor.io),
+them as backups happen:
-[Cronhub](https://cronhub.io), [PagerDuty](https://www.pagerduty.com/),
+
-[ntfy](https://ntfy.sh/), and [Grafana Loki](https://grafana.com/oss/loki/)
+ * [Healthchecks](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#healthchecks-hook)
-and pings these services whenever borgmatic runs. That way, you'll receive an
+ * [Cronitor](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook)
-alert when something goes wrong or (for certain hooks) the service doesn't
+ * [Cronhub](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook)
-hear from borgmatic for a configured interval. See [Healthchecks
+ * [PagerDuty](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook)
-hook](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)
-[Cronitor
+ * [Grafana Loki](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook)
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook),
+ * [Apprise](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook)
-[Cronhub
+
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook),
+The idea is that you'll receive an alert when something goes wrong or when the
-[PagerDuty
+service doesn't hear from borgmatic for a configured interval (if supported).
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook),
+See the documentation links above for configuration information.
-[ntfy
+
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#ntfy-hook),
+While these services and libraries offer different features, you probably only
-and [Loki
+need to use one of them at most.
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook),
-below for how to configure this.
 
-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:
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> 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:
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> 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:
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> 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:
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> 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
+
+<span class="minilink minilink-addedin">New in version 1.8.4</span>
+[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

setup.py

@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-VERSION = '1.8.3'
+VERSION = '1.8.4.dev0'
 
 
 setup(

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,
+        )