logging: add documentation for 'systemd-journal' target

Change-Id: I04c9f81b10ac56c020f537c3ad52026733b5c620

1 files changed, 78 insertions, 0 deletions

diff --git a/common/chapters/logging.adoc b/common/chapters/logging.adoc
index 11ec774..b0a1f5e 100644
--- a/common/chapters/logging.adoc
+++ b/common/chapters/logging.adoc
@@ -290,6 +290,84 @@ with a time-stamp, so you should disable the libosmocore time-stamping
 by issuing the `logging timestamp 0` command.
 
 
+==== Logging to systemd-journal
+
+systemd has been adopted by the majority of modern GNU/Linux distributions.
+Along with various daemons and utilities it provides systemd-journald [1] -
+a daemon responsible for event logging (syslog replacement).  libosmocore
+based applications can log messages directly to systemd-journald.
+
+The key difference from other logging targets is that systemd based logging
+allows to offload rendering of the meta information, such as location
+(file name, line number), subsystem, and logging level, to systemd-journald.
+Furthermore, systemd allows to attach arbitrary meta fields to the logging
+messages [2], which can be used for advanced log filtering.
+
+[1] https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html
+[2] https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html
+
+It was decided to introduce libsystemd as an optional dependency,
+so it needs to be enabled explicitly at configure/build time:
+
+----
+$ ./configure --enable-systemd-logging
+----
+
+NOTE: Recent libosmocore packages provided by Osmocom for Debian and CentOS are
+compiled *with* libsystemd (https://gerrit.osmocom.org/c/libosmocore/+/22651).
+
+You can configure systemd based logging in two ways:
+
+.Example: `systemd-journal` target with offloaded rendering
+----
+log systemd-journal raw <1>
+ logging filter all 1
+ logging level set-all notice
+----
+<1> `raw` logging handler, rendering offloaded to systemd.
+
+In this example, logging messages will be passed to systemd without any meta
+information (time, location, level, category) in the text itself, so all
+the printing parameters like `logging print file` will be ignored.  Instead,
+the meta information is passed separately as _fields_ which can be retrieved
+from the journal and rendered in any preferred way.
+
+----
+# Show Osmocom specific fields
+$ journalctl --fields | grep OSMO
+
+# Filter messages by logging subsystem at run-time
+$ journalctl OSMO_SUBSYS=DMSC -f
+
+# Render specific fields only
+$ journalctl --output=verbose \
+	--output-fields=SYSLOG_IDENTIFIER,OSMO_SUBSYS,CODE_FILE,CODE_LINE,MESSAGE
+----
+
+See `man 7 systemd.journal-fields` for a list of default fields, and
+`man 1 journalctl` for general information and available formatters.
+
+.Example: `systemd-journal` target with libosmocore based rendering
+----
+log systemd-journal <1>
+ logging filter all 1
+ logging print file basename
+ logging print category-hex 0
+ logging print category 1
+ logging print level 1
+ logging timestamp 0 <2>
+ logging color 1 <3>
+ logging level set-all notice
+----
+<1> Generic logging handler, rendering is done by libosmocore.
+<2> Disable timestamping, systemd will timestamp every message anyway.
+<3> Colored messages can be rendered with `journalctl --output=cat`.
+
+In this example, logging messages will be pre-processed by libosmocore before
+being passed to systemd.  No additional fields will be attached, except the
+logging level (`PRIORITY`).  This mode is similar to _syslog_ and _stderr_.
+
+
 ==== Logging to stderr
 
 If you're not running the respective application as a daemon in the