From: Lukáš Ježek Date: Thu, 22 Jul 2021 09:48:35 +0000 (+0200) Subject: doc: logging X-Git-Tag: v5.4.0~2^2~19 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=dbcf9d42aa5911f8011d96217f63563f4d465af7;p=thirdparty%2Fknot-resolver.git doc: logging --- diff --git a/NEWS b/NEWS index 6c4d2b061..fcf818242 100644 --- a/NEWS +++ b/NEWS @@ -4,6 +4,7 @@ Knot Resolver 5.x.y (2021-0m-dd) Improvements ------------ - support apkg tool for packaging workflow (!1178) +- fine grained logging (!1181) Bugfixes -------- @@ -16,6 +17,7 @@ Incompatible changes -------------------- - legacy DoH implementation configuration in net.listen() was renamed from kind="doh" to kind="doh_legacy" (!1180) +- verbose() is deprecated (!1181) Knot Resolver 5.3.2 (2021-05-05) diff --git a/daemon/engine.c b/daemon/engine.c index 079af5c2a..183e8a507 100644 --- a/daemon/engine.c +++ b/daemon/engine.c @@ -145,6 +145,8 @@ static int l_quit(lua_State *L) /** Toggle verbose mode. */ static int l_verbose(lua_State *L) { + kr_log_deprecate(SYSTEM, "use set_log_level() instead of verbose()\n"); + if (lua_isboolean(L, 1) || lua_isnumber(L, 1)) { kr_log_level_set(lua_toboolean(L, 1) == true ? LOG_DEBUG : LOG_DEFAULT_LEVEL); } diff --git a/doc/config-logging-header.rst b/doc/config-logging-header.rst new file mode 100644 index 000000000..551b1bec2 --- /dev/null +++ b/doc/config-logging-header.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +Logging API +=========== + +.. _config_log_groups: + +.. doxygenfile:: lib/log.h + :project: libkres diff --git a/doc/config-logging-monitoring.rst b/doc/config-logging-monitoring.rst index 274025086..ef37ed519 100644 --- a/doc/config-logging-monitoring.rst +++ b/doc/config-logging-monitoring.rst @@ -9,21 +9,65 @@ and sent to logging system for further processing. To read logs use commands usual for your distribution. E.g. on distributions using systemd-journald use command ``journalctl -u kresd@* -f``. -During normal operation only errors and other very important events are logged, -so by default logs from Knot Resolver should contain only couple lines a day. +Knot Resolver supports 6 logging levels - ``crit``, ``err``, ``warning``, +``notice``, ``info``, ``debug``. All levels with the same meaning as is defined +in ``syslog.h``. It is possible change logging level using +:func:`set_log_level` function. + +Logging level ``notice`` is set after start by default, +so logs from Knot Resolver should contain only couple lines a day. For debugging purposes it is possible to enable very verbose logging using :func:`verbose` function. -.. py:function:: verbose([true | false]) +In addition to levels, logging is also divided into the +:ref:`groups `. All groups +are logged by default, but you can enable ``debug`` level for some groups using +:func:`add_log_groups` function. Other groups are logged to the log level +set by :func:`set_log_level`. + +.. py:function:: set_log_level(level) + + :param: String ``'crit'``, ``'err'``, ``'warning'``, ``'notice'``, + ``'info'`` or ``'debug'``. + :return: string Current logging level. + + Set global logging level. + + .. py:function:: verbose([true | false]) + + :param: ``true`` enable ``debug`` level, ``false`` switch to default level (``notice``). + :return: boolean ``true`` when ``debug`` level is enabled. + + Toggle between ``debug`` and ``notice`` log level. Use only for debugging purposes. + On busy systems vebose logging can produce several MB of logs per + second and will slow down operation. + +.. py:function:: get_log_level() + + :return: string Current logging level. + + Show current logging level. + +.. py:function:: get_log_groups() + + :return: table :ref:`Groups ` switched to ``debug`` level. + + Get :ref:`groups ` switched to ``debug`` level. + +.. py:function:: add_log_groups([string | table]) + + :param: :ref:`Groups ` to switch to ``debug`` level. + + Set debug level for selected :ref:`groups `. + +.. py:function:: del_log_groups([string | table]) - :param: ``true`` to enable, ``false`` to disable verbose logging. - :return: boolean Current state of verbose logging. + :param: :ref:`Groups ` switched to global logging level. - Toggle global verbose logging. Use only for debugging purposes. - On busy systems vebose logging can produce several MB of logs per - second and will slow down operation. + Switch selected :ref:`groups ` to logging level set + by :func:`set_log_level`. -It is also possible to obtain verbose logs for *a single request*, see chapter :ref:`mod-http-trace`. +It is also possible to enable ``debug`` logging level for *a single request*, see chapter :ref:`mod-http-trace`. Less verbose logging for DNSSEC validation errors can be enabled using :ref:`mod-bogus_log` module. @@ -48,3 +92,4 @@ Additional monitoring and debugging methods are described below. If none of thes modules-detect_time_skew modules-detect_time_jump config-debugging + config-logging-header diff --git a/doc/upgrading.rst b/doc/upgrading.rst index ae2394d39..a794522f7 100644 --- a/doc/upgrading.rst +++ b/doc/upgrading.rst @@ -22,6 +22,8 @@ newer versions when they are released. `_. Preferred way to manage :ref:`systemd-multiple-instances` is to use a process manager, e.g. systemd_ or supervisord_. +* Function :func:`verbose` is deprecated and will be eventually removed. + Prefered way to change logging level is use to :func:`set_log_level`. .. _`systemd`: https://systemd.io/ .. _`supervisord`: http://supervisord.org/ @@ -33,6 +35,8 @@ Configuration file ------------------ * ``kind='doh'`` in :func:`net.listen` was renamed to ``kind='doh_legacy'``. It is recommended to switch to the new DoH implementation with ``kind='doh2'``. +* :func:`verbose` is deprecated. In case you want to change logging level, + there is new function :func:`set_log_level`. Packagers & Developers ---------------------- diff --git a/lib/log.h b/lib/log.h index 9d254084b..03bf6cdff 100644 --- a/lib/log.h +++ b/lib/log.h @@ -8,9 +8,8 @@ #include #include "lib/defines.h" - -#define LOG_DEFAULT_LEVEL LOG_NOTICE -#define LOG_GNUTLS_LEVEL 5 +#define LOG_DEFAULT_LEVEL LOG_NOTICE /**< Default level is ``notice``. */ +#define LOG_GNUTLS_LEVEL 5 /**< GnuTLS level is 5. */ /* Targets */ @@ -77,50 +76,55 @@ typedef struct { enum kr_log_group g_val; } log_group_names_t; -#define LOG_GRP_SYSTEM_TAG "system" -#define LOG_GRP_CACHE_TAG "cache" -#define LOG_GRP_IO_TAG "io" -#define LOG_GRP_NETWORK_TAG "net" -#define LOG_GRP_TA_TAG "ta" -#define LOG_GRP_TLS_TAG "tls" -#define LOG_GRP_GNUTLS_TAG "gnutls" -#define LOG_GRP_TLSCLIENT_TAG "tls_cl" -#define LOG_GRP_XDP_TAG "xdp" -#define LOG_GRP_ZIMPORT_TAG "zimprt" -#define LOG_GRP_ZSCANNER_TAG "zscann" -#define LOG_GRP_DOH_TAG "doh" -#define LOG_GRP_DNSSEC_TAG "dnssec" -#define LOG_GRP_HINT_TAG "hint" -#define LOG_GRP_PLAN_TAG "plan" -#define LOG_GRP_ITERATOR_TAG "iterat" -#define LOG_GRP_VALIDATOR_TAG "valdtr" -#define LOG_GRP_RESOLVER_TAG "resolv" -#define LOG_GRP_SELECTION_TAG "select" -#define LOG_GRP_ZCUT_TAG "zoncut" -#define LOG_GRP_COOKIES_TAG "cookie" -#define LOG_GRP_STATISTICS_TAG "statis" -#define LOG_GRP_REBIND_TAG "rebind" -#define LOG_GRP_WORKER_TAG "worker" -#define LOG_GRP_POLICY_TAG "policy" -#define LOG_GRP_TASENTINEL_TAG "tasent" -#define LOG_GRP_TASIGNALING_TAG "tasign" -#define LOG_GRP_TAUPDATE_TAG "taupd" -#define LOG_GRP_DAF_TAG "daf" -#define LOG_GRP_DETECTTIMEJUMP_TAG "timejm" -#define LOG_GRP_DETECTTIMESKEW_TAG "timesk" -#define LOG_GRP_GRAPHITE_TAG "graphi" -#define LOG_GRP_PREFILL_TAG "prefil" -#define LOG_GRP_PRIMING_TAG "primin" -#define LOG_GRP_SRVSTALE_TAG "srvstl" -#define LOG_GRP_WATCHDOG_TAG "wtchdg" -#define LOG_GRP_NSID_TAG "nsid" -#define LOG_GRP_DNSTAP_TAG "dnstap" -#define LOG_GRP_TESTS_TAG "tests" -#define LOG_GRP_DOTAUTH_TAG "dotaut" -#define LOG_GRP_HTTP_TAG "http" -#define LOG_GRP_CONTROL_TAG "contrl" -#define LOG_GRP_MODULE_TAG "module" -#define LOG_GRP_DEVEL_TAG "devel" +/** + * @name Group names + */ +///@{ +#define LOG_GRP_SYSTEM_TAG "system" /**< ``system``: operations related to system */ +#define LOG_GRP_CACHE_TAG "cache" /**< ``cache``: operations related to cache */ +#define LOG_GRP_IO_TAG "io" /**< ``io``: operations related to io */ +#define LOG_GRP_NETWORK_TAG "net" /**< ``net``: operations related to network */ +#define LOG_GRP_TA_TAG "ta" /**< ``ta``: operations related to trush anchors */ +#define LOG_GRP_TLS_TAG "tls" /**< ``tls``: operations related to TLS */ +#define LOG_GRP_GNUTLS_TAG "gnutls" /**< ``gnutls``: operations related to GnuTLS */ +#define LOG_GRP_TLSCLIENT_TAG "tls_cl" /**< ``tls_cl``: operations related to TLS client */ +#define LOG_GRP_XDP_TAG "xdp" /**< ``xdp``: operations related to XDP */ +#define LOG_GRP_ZIMPORT_TAG "zimprt" /**< ``zimprt``: operations related to zimport */ +#define LOG_GRP_ZSCANNER_TAG "zscann" /**< ``zscann``: operations related to zscanner */ +#define LOG_GRP_DOH_TAG "doh" /**< ``doh``: operations related to DoH */ +#define LOG_GRP_DNSSEC_TAG "dnssec" /**< ``dnssec``: operations related to DNSSEC */ +#define LOG_GRP_HINT_TAG "hint" /**< ``hint``: operations related to static hints */ +#define LOG_GRP_PLAN_TAG "plan" /**< ``plan``: operations related to resolution plan */ +#define LOG_GRP_ITERATOR_TAG "iterat" /**< ``iterat``: operations related to iterate layer */ +#define LOG_GRP_VALIDATOR_TAG "valdtr" /**< ``valdtr``: operations related to validate layer */ +#define LOG_GRP_RESOLVER_TAG "resolv" /**< ``resolv``: operations related to resolving */ +#define LOG_GRP_SELECTION_TAG "select" /**< ``select``: operations related to server selection */ +#define LOG_GRP_ZCUT_TAG "zoncut" /**< ``zonecut``: operations related to zone cut */ +#define LOG_GRP_COOKIES_TAG "cookie" /**< ``cookie``: operations related to cookies */ +#define LOG_GRP_STATISTICS_TAG "statis" /**< ``statis``: operations related to statistics */ +#define LOG_GRP_REBIND_TAG "rebind" /**< ``rebind``: operations related to rebinding */ +#define LOG_GRP_WORKER_TAG "worker" /**< ``worker``: operations related to worker layer */ +#define LOG_GRP_POLICY_TAG "policy" /**< ``policy``: operations related to policy */ +#define LOG_GRP_TASENTINEL_TAG "tasent" /**< ``tasent``: operations related to TA sentinel */ +#define LOG_GRP_TASIGNALING_TAG "tasign" /**< ``tasign``: operations related to TA signal query */ +#define LOG_GRP_TAUPDATE_TAG "taupd" /**< ``taupd``: operations related to TA update */ +#define LOG_GRP_DAF_TAG "daf" /**< ``daf``: operations related to DAF */ +#define LOG_GRP_DETECTTIMEJUMP_TAG "timejm" /**< ``timejm``: operations related to time jump */ +#define LOG_GRP_DETECTTIMESKEW_TAG "timesk" /**< ``timesk``: operations related to time skew */ +#define LOG_GRP_GRAPHITE_TAG "graphi" /**< ``graphi``: operations related to graphite */ +#define LOG_GRP_PREFILL_TAG "prefil" /**< ``prefil``: operations related to prefill */ +#define LOG_GRP_PRIMING_TAG "primin" /**< ``primin``: operations related to priming */ +#define LOG_GRP_SRVSTALE_TAG "srvstl" /**< ``srvstl``: operations related to serve stale */ +#define LOG_GRP_WATCHDOG_TAG "wtchdg" /**< ``wtchdg``: operations related to watchdog */ +#define LOG_GRP_NSID_TAG "nsid" /**< ``nsid``: operations related to NSID */ +#define LOG_GRP_DNSTAP_TAG "dnstap" /**< ``dnstap``: operations related to dnstap */ +#define LOG_GRP_TESTS_TAG "tests" /**< ``tests``: operations related to tests */ +#define LOG_GRP_DOTAUTH_TAG "dotaut" /**< ``dotaut``: operations related to DoH authorization */ +#define LOG_GRP_HTTP_TAG "http" /**< ``http``: operations related to http */ +#define LOG_GRP_CONTROL_TAG "contrl" /**< ``contrl``: operations related to TTY control */ +#define LOG_GRP_MODULE_TAG "module" /**< ``module``: For logging in user-defined modules */ +#define LOG_GRP_DEVEL_TAG "devel" /**< ``devel``: For development purposes */ +///@} KR_EXPORT bool kr_log_group_is_set(enum kr_log_group group); @@ -155,6 +159,14 @@ void kr_log_init(log_level_t level, log_target_t target); #define TO_STR(x) TO_STR_A(x) #define SD_JOURNAL_METADATA "CODE_FILE=" __FILE__, "CODE_LINE=" TO_STR(__LINE__), "" +/** + * Logging function for user modules. Uses group LOG_GRP_MODULE and ``info`` level. + * @param fmt Format string + */ +#define kr_log(fmt, ...) \ + kr_log_fmt(LOG_GRP_MODULE, LOG_INFO, SD_JOURNAL_METADATA, \ + "[%-6s] " fmt, LOG_GRP_MODULE_TAG, ## __VA_ARGS__) + #define kr_log_debug(grp, fmt, ...) \ kr_log_fmt(LOG_GRP_ ## grp, LOG_DEBUG, SD_JOURNAL_METADATA, \ "[%-6s] " fmt, LOG_GRP_ ## grp ## _TAG, ## __VA_ARGS__) @@ -177,10 +189,6 @@ void kr_log_init(log_level_t level, log_target_t target); #define kr_log_deprecate(grp, fmt, ...) \ kr_log_fmt(LOG_GRP_ ## grp, LOG_WARNING,SD_JOURNAL_METADATA, \ "[%-6s] deprecation WARNING: " fmt, LOG_GRP_ ## grp ## _TAG, ## __VA_ARGS__) -#define kr_log(fmt, ...) \ - kr_log_fmt(LOG_GRP_MODULE, LOG_INFO, SD_JOURNAL_METADATA, \ - "[%-6s] " fmt, LOG_GRP_MODULE_TAG, ## __VA_ARGS__) - #define KR_LOG_LEVEL_IS(exp) ((kr_log_level >= (exp)) ? true : false)