doc: document debugging options

diff --git a/doc/config-debugging.rst b/doc/config-debugging.rst
new file mode 100644 (file)
index 0000000..9de4295
--- /dev/null
+++ b/doc/config-debugging.rst
@@ -0,0 +1,30 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Debugging options
+=================
+
+In case the resolver crashes, it is often helpful to collect a coredump from
+the crashed process. Configuring the system to collect coredump from crashed
+process is out of the scope of this documentation, but some tips can be found
+`here <https://lists.nic.cz/pipermail/knot-resolver-users/2019/000239.html>`_.
+
+Kresd uses *assumptions*, which are checks that should always pass and indicate
+some weird or unexpected state if they don't. In such cases, they show up in
+the log as errors. By default, the process recovers from those states, but the
+behaviour can be changed with the following options to aid further debugging.
+
+.. envvar:: debugging.assumption_abort = false|true
+
+   :return: boolean (default: false)
+
+   Allow the process to be aborted in case it encounters a failed assumption.
+
+.. envvar:: debugging.assumption_fork = true|false
+
+   :return: boolean (default: true)
+
+   If a proccess should be aborted, it can be done in two ways. When this is
+   set to true (default), a child is forked and aborted to obtain a coredump,
+   while the parent process recovers and keeps running. This can be useful to
+   debug a rare issue that occurs in production, since it doesn't affect the
+   main process.

diff --git a/doc/config-logging-monitoring.rst b/doc/config-logging-monitoring.rst
index 6f21b4a9883d1415c65608b287499247898037a4..27402508620301f1a9c021f74442b96f7840c921 100644 (file)
--- a/doc/config-logging-monitoring.rst
+++ b/doc/config-logging-monitoring.rst
@@ -47,3 +47,4 @@ Additional monitoring and debugging methods are described below. If none of thes
    modules-ta_signal_query
    modules-detect_time_skew
    modules-detect_time_jump
+   config-debugging