diff --git a/doc/config-debugging.rst b/doc/config-debugging.rst new file mode 100644 index 0000000000000000000000000000000000000000..9de4295fd805acce77eb68f30c12de2e779bb517 --- /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 --- 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