This is merely a historical archive of years 2008-2021, before the migration to mailman3.
A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.
laforge gerrit-no-reply at lists.osmocom.orglaforge has submitted this change. ( https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/22844 ) Change subject: logging: add documentation for 'systemd-journal' target ...................................................................... logging: add documentation for 'systemd-journal' target Change-Id: I04c9f81b10ac56c020f537c3ad52026733b5c620 --- M common/chapters/logging.adoc 1 file changed, 78 insertions(+), 0 deletions(-) Approvals: laforge: Looks good to me, approved Jenkins Builder: Verified 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 @@ 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 -- To view, visit https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/22844 To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-Change-Id: I04c9f81b10ac56c020f537c3ad52026733b5c620 Gerrit-Change-Number: 22844 Gerrit-PatchSet: 2 Gerrit-Owner: fixeria <vyanitskiy at sysmocom.de> Gerrit-Reviewer: Jenkins Builder Gerrit-Reviewer: laforge <laforge at osmocom.org> Gerrit-Reviewer: pespin <pespin at sysmocom.de> Gerrit-MessageType: merged -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20210213/1c911361/attachment.htm>