From 8a5a962a11ef764c6e0eb87da919f5bc34dd569d Mon Sep 17 00:00:00 2001 From: =?utf8?q?Luk=C3=A1=C5=A1=20Ondr=C3=A1=C4=8Dek?= Date: Mon, 24 Mar 2025 16:24:54 +0100 Subject: [PATCH] doc/dev: add logging overview --- doc/dev/logging_api.rst | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/doc/dev/logging_api.rst b/doc/dev/logging_api.rst index 09b705c8b..a4a093a73 100644 --- a/doc/dev/logging_api.rst +++ b/doc/dev/logging_api.rst @@ -3,6 +3,44 @@ Logging API reference ===================== +Logging overview +---------------- + +Kresd process uses one of several logging targets according to its configuration; +it can log to ``stdout``, ``stderr`` and ``syslog`` (either via ``syslog`` function of via ``libsystemd``). +There is also rarely used async-signal-safe way of logging defined in ``lib/sigsafe.h``, +which tries to be as consistent with the standard logging as possible, +though some inconsistencies arise to avoid unsafe function calls like ``syslog``. + +Based on how knot-resolver was executed, there are different ways of handling logs: + +With systemd service using manager (the standard way) +each process (incl. manager, etc) uses ``syslog``/``libsystemd`` directly, +sigsafe variant prints lines prefixed with loglevel to ``stderr``, +which should be handled by systemd the same way. +Using systemd without manager (the legacy way) works the same. + +When using manager with non-systemd syslog, +all processes use directly ``syslog``, +sigsafe uses the ``stderr`` with prefixing as before, +which is now handled by supervisor resending the output using ``syslog``. +The form of the messages may be a little different, but all end up in the syslog. +As supervisor cannot handle syslog loglevels by itself, +all sigsafe messages use the same level in this case. + +When using manager with stdout logging (``./poe run``), +each process prints to stdout, +which is prefixed with timestamp and process name by supervisor. +Sigsafe works the same (no loglevel prefixing). + +When spawning kresd on your own, logging target depends on your configuration. +If logging to ``stdout``/``stderr``, sigsafe is consistent; +if using ``syslog``, you need to handle also ````-prefixed lines on ``stderr``. + + +API reference +------------- + .. _config_log_groups: .. doxygenfile:: lib/log.h -- 2.47.2