<p>fixeria has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/22844">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">logging: add documentation for 'systemd-journal' target<br><br>Change-Id: I04c9f81b10ac56c020f537c3ad52026733b5c620<br>---<br>M common/chapters/logging.adoc<br>1 file changed, 78 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/44/22844/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/common/chapters/logging.adoc b/common/chapters/logging.adoc</span><br><span>index 11ec774..b0a1f5e 100644</span><br><span>--- a/common/chapters/logging.adoc</span><br><span>+++ b/common/chapters/logging.adoc</span><br><span>@@ -290,6 +290,84 @@</span><br><span> by issuing the `logging timestamp 0` command.</span><br><span> </span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+==== Logging to systemd-journal</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+systemd has been adopted by the majority of modern GNU/Linux distributions.</span><br><span style="color: hsl(120, 100%, 40%);">+Along with various daemons and utilities it provides systemd-journald [1] -</span><br><span style="color: hsl(120, 100%, 40%);">+a daemon responsible for event logging (syslog replacement).  libosmocore</span><br><span style="color: hsl(120, 100%, 40%);">+based applications can log messages directly to systemd-journald.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The key difference from other logging targets is that systemd based logging</span><br><span style="color: hsl(120, 100%, 40%);">+allows to offload rendering of the meta information, such as location</span><br><span style="color: hsl(120, 100%, 40%);">+(file name, line number), subsystem, and logging level, to systemd-journald.</span><br><span style="color: hsl(120, 100%, 40%);">+Furthermore, systemd allows to attach arbitrary meta fields to the logging</span><br><span style="color: hsl(120, 100%, 40%);">+messages [2], which can be used for advanced log filtering.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[1] https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html</span><br><span style="color: hsl(120, 100%, 40%);">+[2] https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+It was decided to introduce libsystemd as an optional dependency,</span><br><span style="color: hsl(120, 100%, 40%);">+so it needs to be enabled explicitly at configure/build time:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+$ ./configure --enable-systemd-logging</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NOTE: Recent libosmocore packages provided by Osmocom for Debian and CentOS are</span><br><span style="color: hsl(120, 100%, 40%);">+compiled *with* libsystemd (https://gerrit.osmocom.org/c/libosmocore/+/22651).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You can configure systemd based logging in two ways:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Example: `systemd-journal` target with offloaded rendering</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+log systemd-journal raw <1></span><br><span style="color: hsl(120, 100%, 40%);">+ logging filter all 1</span><br><span style="color: hsl(120, 100%, 40%);">+ logging level set-all notice</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> `raw` logging handler, rendering offloaded to systemd.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In this example, logging messages will be passed to systemd without any meta</span><br><span style="color: hsl(120, 100%, 40%);">+information (time, location, level, category) in the text itself, so all</span><br><span style="color: hsl(120, 100%, 40%);">+the printing parameters like `logging print file` will be ignored.  Instead,</span><br><span style="color: hsl(120, 100%, 40%);">+the meta information is passed separately as _fields_ which can be retrieved</span><br><span style="color: hsl(120, 100%, 40%);">+from the journal and rendered in any preferred way.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+# Show Osmocom specific fields</span><br><span style="color: hsl(120, 100%, 40%);">+$ journalctl --fields | grep OSMO</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+# Filter messages by logging subsystem at run-time</span><br><span style="color: hsl(120, 100%, 40%);">+$ journalctl OSMO_SUBSYS=DMSC -f</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+# Render specific fields only</span><br><span style="color: hsl(120, 100%, 40%);">+$ journalctl --output=verbose \</span><br><span style="color: hsl(120, 100%, 40%);">+     --output-fields=SYSLOG_IDENTIFIER,OSMO_SUBSYS,CODE_FILE,CODE_LINE,MESSAGE</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+See `man 7 systemd.journal-fields` for a list of default fields, and</span><br><span style="color: hsl(120, 100%, 40%);">+`man 1 journalctl` for general information and available formatters.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.Example: `systemd-journal` target with libosmocore based rendering</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+log systemd-journal <1></span><br><span style="color: hsl(120, 100%, 40%);">+ logging filter all 1</span><br><span style="color: hsl(120, 100%, 40%);">+ logging print file basename</span><br><span style="color: hsl(120, 100%, 40%);">+ logging print category-hex 0</span><br><span style="color: hsl(120, 100%, 40%);">+ logging print category 1</span><br><span style="color: hsl(120, 100%, 40%);">+ logging print level 1</span><br><span style="color: hsl(120, 100%, 40%);">+ logging timestamp 0 <2></span><br><span style="color: hsl(120, 100%, 40%);">+ logging color 1 <3></span><br><span style="color: hsl(120, 100%, 40%);">+ logging level set-all notice</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> Generic logging handler, rendering is done by libosmocore.</span><br><span style="color: hsl(120, 100%, 40%);">+<2> Disable timestamping, systemd will timestamp every message anyway.</span><br><span style="color: hsl(120, 100%, 40%);">+<3> Colored messages can be rendered with `journalctl --output=cat`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In this example, logging messages will be pre-processed by libosmocore before</span><br><span style="color: hsl(120, 100%, 40%);">+being passed to systemd.  No additional fields will be attached, except the</span><br><span style="color: hsl(120, 100%, 40%);">+logging level (`PRIORITY`).  This mode is similar to _syslog_ and _stderr_.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> ==== Logging to stderr</span><br><span> </span><br><span> If you're not running the respective application as a daemon in the</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/22844">change 22844</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/22844"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: osmo-gsm-manuals </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I04c9f81b10ac56c020f537c3ad52026733b5c620 </div>
<div style="display:none"> Gerrit-Change-Number: 22844 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: fixeria <vyanitskiy@sysmocom.de> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>