Healthchecks

Healthchecks is a service that provides "instant alerts when your cron jobs fail silently," and borgmatic has built-in integration with it. Once you create a Healthchecks account and project on their site, all you need to do is configure borgmatic with the unique "Ping URL" for your project. Here's an example:

healthchecks:
    ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a

Prior to version 1.8.0 Put this option in the hooks: section of your configuration.

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.

Then, if the actions complete successfully, borgmatic notifies Healthchecks of the success and includes borgmatic logs in the payload data sent to Healthchecks. This means that borgmatic logs show up in the Healthchecks UI, although be aware that Healthchecks currently has a 100-kilobyte limit for the logs in each ping.

If an error occurs during any action or hook, borgmatic notifies Healthchecks, also tacking on logs including the error itself. But the logs are only included for errors that occur when a create, prune, compact, or check action is run.

You can customize the verbosity of the logs that are sent to Healthchecks with borgmatic's --monitoring-verbosity flag. The --list and --stats flags may also be of use. See create action documentation for more information. Additionally, see the borgmatic configuration file for additional Healthchecks options.

New in version 2.0.0Set the defaults for these flags in your borgmatic configuration via the monitoring_verbosity, list, and statistics options.

You can configure Healthchecks to notify you by a variety of mechanisms when backups fail or it doesn't hear from borgmatic for a certain period of time.

Full configuration

# Configuration for a monitoring integration with Healthchecks. Create
# an account at https://healthchecks.io (or self-host Healthchecks) if
# you'd like to use this service. See borgmatic monitoring
# documentation for details.
healthchecks:
    # Healthchecks ping URL or UUID to notify when a backup
    # begins, ends, errors, or to send only logs.
    ping_url: https://hc-ping.com/your-uuid-here

    # Verify the TLS certificate of the ping URL host. Defaults to
    # true.
    verify_tls: false

    # Send borgmatic logs to Healthchecks as part of the "finish",
    # "fail", and "log" states. Defaults to true.
    send_logs: false

    # Number of bytes of borgmatic logs to send to Healthchecks,
    # ideally the same as PING_BODY_LIMIT configured on the
    # Healthchecks server. Set to 0 to send all logs and disable
    # this truncation. Defaults to 100000.
    ping_body_limit: 200000

    # List of one or more monitoring states to ping for: "start",
    # "finish", "fail", and/or "log". Defaults to pinging for all
    # states.
    states:
        - finish

    # Create the check if it does not exist. Only works with
    # the slug URL scheme (https://hc-ping.com/<ping-key>/<slug>
    # as opposed to https://hc-ping.com/<uuid>).
    # Defaults to false.
    create_slug: true