doc: logging

diff --git a/NEWS b/NEWS
index 6c4d2b06179550c97c8193fc600a19ed32c6da1a..fcf81824233b841e5ad124361dcbb3df71ab9748 100644 (file)
--- 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 079af5c2ae1b11974a1cd562614cb48de09d893c..183e8a5078dd481c865d039754b534602b8fc2c8 100644 (file)
--- 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 (file)
index 0000000..551b1be
--- /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 27402508620301f1a9c021f74442b96f7840c921..ef37ed519007f9b4346d590b5687895641f9fc5b 100644 (file)
--- 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 <config_log_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 <config_log_groups>` switched to ``debug`` level.
+
+  Get :ref:`groups <config_log_groups>` switched to ``debug`` level.
+
+.. py:function:: add_log_groups([string | table])
+
+  :param: :ref:`Groups <config_log_groups>` to switch to ``debug`` level.
+
+  Set debug level for selected :ref:`groups <config_log_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 <config_log_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 <config_log_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 ae2394d399319de1b0b641120ffc2a433f773aa2..a794522f710e7f4014112129cee34e7c581ffc0f 100644 (file)
--- a/doc/upgrading.rst
+++ b/doc/upgrading.rst
@@ -22,6 +22,8 @@ newer versions when they are released.
   <https://gitlab.nic.cz/knot/knot-resolver/-/issues/631>`_.
   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 9d254084b26f7b7f9b0dfbc91dca2d8b866bc2fc..03bf6cdff916919ede1f429a015ee6d3caab2f7d 100644 (file)
--- a/lib/log.h
+++ b/lib/log.h
@@ -8,9 +8,8 @@
 #include <syslog.h>
 #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)