Apprise hook documentation (#715).
This commit is contained in:
parent
9e14f209f1
commit
f011431463
5 changed files with 111 additions and 34 deletions
7
NEWS
7
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
|
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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
2
setup.py
2
setup.py
|
@ -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(
|
||||||
|
|
|
@ -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,
|
||||||
|
)
|
||||||
|
|
Loading…
Reference in a new issue