Apprise hook documentation (#715).

This commit is contained in:
Dan Helfman 2023-10-04 19:23:53 -07:00
parent 9e14f209f1
commit f011431463
5 changed files with 111 additions and 34 deletions

7
NEWS
View file

@ -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 1.8.3
* #665: BREAKING: Simplify logging logic as follows: Syslog verbosity is now disabled by * #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 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 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 default to 1 (info about steps borgmatic is taking) instead of 0. And both syslog logging and
file logging can be enabled simultaneously. 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: documentation for more information:
https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook 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 * #753: When "archive_name_format" is not set, filter archives using the default archive name

View file

@ -1324,12 +1324,12 @@ properties:
example: "gotify://hostname/token" example: "gotify://hostname/token"
label: label:
type: string type: string
example: mastodon example: gotify
description: | 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: example:
- url: "kodi://user@hostname" - url: "kodi://user@hostname"
label: kodi label: kodi

View file

@ -36,28 +36,24 @@ below for how to configure this.
### Third-party monitoring services ### 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 ### Third-party monitoring software
@ -146,7 +142,7 @@ healthchecks:
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `hooks:` section of your configuration. 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`, backup begins, ends, or errors, but only when any of the `create`, `prune`,
`compact`, or `check` actions are run. `compact`, or `check` actions are run.
@ -190,7 +186,7 @@ cronitor:
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `hooks:` section of your configuration. 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`, begins, ends, or errors, but only when any of the `prune`, `compact`,
`create`, or `check` actions are run. Then, if the actions complete `create`, or `check` actions are run. Then, if the actions complete
successfully or errors, borgmatic notifies Cronitor accordingly. 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 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `hooks:` section of your configuration. 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`, begins, ends, or errors, but only when any of the `prune`, `compact`,
`create`, or `check` actions are run. Then, if the actions complete `create`, or `check` actions are run. Then, if the actions complete
successfully or errors, borgmatic notifies Cronhub accordingly. 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 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `hooks:` section of your configuration. 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`, whenever backups fail, but only when any of the `create`, `prune`, `compact`,
or `check` actions are run. Note that borgmatic does not contact PagerDuty or `check` actions are run. Note that borgmatic does not contact PagerDuty
when a backup starts or when it ends without error. when a backup starts or when it ends without error.
@ -340,7 +336,7 @@ loki:
url: http://localhost:3100/loki/api/v1/push 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 of the `prune`, `compact`, `create`, or `check` actions are run. Then, after
the actions complete, borgmatic notifies Loki of success or failure. 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 ## 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

View file

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

View file

@ -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() flexmock(module.logger).should_receive('info').once()
module.ping_monitor( module.ping_monitor(
@ -206,3 +206,18 @@ def test_ping_monitor_warning_for_no_services():
monitoring_log_level=1, monitoring_log_level=1,
dry_run=False, 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,
)