Loki

New in version 1.8.3 Grafana Loki is a "horizontally scalable, highly available, multi-tenant log aggregation system inspired by Prometheus." borgmatic has built-in integration with Loki, sending both backup status and optionally borgmatic logs.

You can configure borgmatic to use either a self-hosted Loki instance or a Grafana Cloud account. Start by setting your Loki API push URL. Here's an example:

loki:
    url: http://localhost:3100/loki/api/v1/push

    labels:
        app: borgmatic
        hostname: example.org

With this configuration, borgmatic notifies your Loki instance of starting, success, or failure when any of the create, prune, compact, or check actions run.

This hook supports sending arbitrary labels to Loki. At least one label is required.

There are also a few placeholders you can optionally use as label values:

• __config: name of the borgmatic configuration file
• __config_path: full path of the borgmatic configuration file
• __hostname: the local machine hostname

These placeholders are only substituted for the whole label value, not interpolated into a larger string. For instance:

loki:
    url: http://localhost:3100/loki/api/v1/push

    labels:
        app: borgmatic
        config: __config
        hostname: __hostname

Also check out this Loki dashboard for borgmatic if you'd like to see your backup logs and statistics in one place. Note that it does require sending logs (see below).

Sending logs

borgmatic can include logs in the data sent to Loki when a backup starts, finishes, or fails.

New in version 2.1.0 There is a send_logs option to enable log sending:

loki:
    url: http://localhost:3100/loki/api/v1/push

    labels:
        app: borgmatic

    send_logs: true

To avoid revealing private log information to third-party services, log sending is not enabled by default when send_logs is omitted.

Prior to version 2.1.0 Logs were sent by default, and the send_logs option was not yet supported.

You can customize the verbosity of the logs that are sent with borgmatic's --monitoring-verbosity flag. The --list and --stats flags may also be of use. See create action documentation for more information.

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

Mutual TLS authentication

New in version 2.1.5 Since Loki does not come with a built-in authentication layer (doc), this feature is typically used alongside a reverse proxy (such as nginx or Traefik) that handles mTLS termination.

If your setup is configured for mTLS authentication, you can provide a client certificate and private key:

loki:
    url: https://loki.fqdn/loki/api/v1/push

    labels:
        app: borgmatic

    tls:
        cert_path: /etc/borgmatic/loki-client.crt
        key_path: /etc/borgmatic/loki-client.key

Both cert_path and key_path must be PEM-encoded. They are passed directly to the underlying HTTP client, so the standard mutual TLS handshake is performed for every request borgmatic sends to Loki.