diff --git a/NEWS b/NEWS index e7fecd88..2f6a929b 100644 --- a/NEWS +++ b/NEWS @@ -11,7 +11,9 @@ * #1211: Fix an error about the runtime directory getting excluded by tweaking its logic and lowering the error to a warning. * #1212: Fix an error when restoring multiple directory-format database dumps at once. - * When syslog verbosity is enabled, log to systemd's journal (if present) with structured data. + * When syslog verbosity is enabled, log to systemd's journal (if present) with + structured data. See the documentation for more information: + https://torsion.org/borgmatic/reference/command-line/logging/#systemd-journal 2.0.13 * #1054: Allow the Btrfs hook to create and delete snapshots even when running diff --git a/docs/reference/command-line/logging.md b/docs/reference/command-line/logging.md index 221e5ab3..317f93b6 100644 --- a/docs/reference/command-line/logging.md +++ b/docs/reference/command-line/logging.md @@ -34,6 +34,13 @@ Additionally, for the `create` action in particular, you can include the that are new or changed since the last backup. +### JSON logging + +New in version 2.1.0With the +`--log-json` flag, borgmatic logs both its own logs and Borg's output as JSON. +The `--log-json` flag applies to console output and any log file (see below). + + ## Logging to syslog By default, borgmatic only logs its output to the console. You can enable @@ -66,6 +73,40 @@ systemd, try running `journalctl -xe`. Otherwise, try viewing logged to syslog by default whenever run at a non-interactive console. +### Systemd journal + +New in version 2.1.0If the syslog +verbosity is set and systemd's journal is present, then borgmatic sends +structured logs to the journal instead of plain text. This allows you to query +logs by particular fields. For instance: + +```bash +journalctl --catalog --pager-end SYSLOG_IDENTIFIER=borgmatic +``` + +Or to view just borgmatic warning and error logs: + +```bash +journalctl --catalog --pager-end SYSLOG_IDENTIFIER=borgmatic --priority warning..alert +``` + +The fields borgmatic sends are: + + * `MESSAGE`: the log message + * `PRIORITY`: the [numeric priority level](https://wiki.archlinux.org/title/Systemd/Journal#Priority_level) for the log entry + * `SYSLOG_IDENTIFIER`: `borgmatic` + * `SYSLOG_PID`: borgmatic's process ID + +You can also output these stuctured logs as JSON: + +```bash +journalctl --output=json SYSLOG_IDENTIFIER=borgmatic +``` + +Note that systemd's journal adds its own fields to the JSON on top of the fields +that borgmatic logs. + + ### Rate limiting If you are using rsyslog or systemd's journal, be aware that by default they