Upgrade guide and running recursor updates to new rec_control trace-regex

diff --git a/pdns/recursordist/docs/running.rst b/pdns/recursordist/docs/running.rst
index 88b4b26de690768f7d4bfb2a73103d67a7ee0e6c..0b73d078b65314bbd0432ca7bb84f5e5c8ce3260 100644 (file)
--- a/pdns/recursordist/docs/running.rst
+++ b/pdns/recursordist/docs/running.rst
@@ -76,21 +76,39 @@ When debugging resolving issues, it can be advantageous to have a dump of all th
 
   rec_control dump-cache /tmp/cache
 
+.. _tracing:
+
 Tracing Queries
 ---------------
-To investigate failures with resolving certain domain names, the PowerDNS Recursor features a "tracing" infrastructure.
-This infrastructure will log every step the Recursor takes to resolve a name and will log all DNSSEC related information as well.
+To investigate failures with resolving certain domain names, the PowerDNS :program:`Recursor` features a tracing infrastructure.
+This infrastructure will log every step the :program:`Recursor` takes to resolve a name and will log all DNSSEC related information as well.
 
 To enable tracing for all queries, enable the :ref:`setting-trace` setting.
+Trace infomration will be written to the log.
 
 .. warning::
 
   Enabling tracing for all queries on a system with a high query rate can severely impact performance.
 
-Tracing can also be enabled at runtime, without restarting the Recursor, for specific domains.
+Tracing can also be enabled at runtime, without restarting the :program:`Recursor`, for specific domains.
 These specific domains can be specified as a regular expression.
 This can be done using :doc:`rec_control trace-regex <manpages/rec_control.1>`::
 
-    rec_control trace-regex '.*\.example.com\.$'
+  rec_control trace-regex '.*\.example.com\.$'
 
 Will enable tracing for any query *in* the example.com domain (but not example.com itself).
+
+Since version 4.9.0 ``trace_regex`` takes an extra file argument.
+Trace information will be written to the file and not to the log.
+If the file argument is a hyphen (``-``), trace information will be written to the standard output stream.
+For example::
+
+  rec_control trace-regex 'example\.com\.$' - | grep asking
+
+will show which authoritative servers were consulted.
+
+Do not forget to disable tracing after diagnosis is done::
+
+  rec_control trace-regex
+
+

diff --git a/pdns/recursordist/docs/upgrade.rst b/pdns/recursordist/docs/upgrade.rst
index 8818dd06b6b53bc1cd9f25aff597b39099cca69b..5f5e2b6c07a5fc6ccbc356e1e61c70ae80ea5bd8 100644 (file)
--- a/pdns/recursordist/docs/upgrade.rst
+++ b/pdns/recursordist/docs/upgrade.rst
@@ -15,6 +15,10 @@ This is now resolved, but has the consequence that some metrics (in particular r
 This affects the results shown by ``rec_control get-qtypelist`` and the ``response-by-qtype``, ``response-sizes`` and ``response-by-rcode`` items returned by the ``/api/v1/servers/localhost/statistics`` API endpoint.
 Additionally, most ``RCodes`` and ``QTypes`` that are marked ``Unassigned``, ``Reserved`` or ``Obsolete`` by IANA are not accounted, to reduce the memory consumed by these metrics.
 
+:program:`rec_control`
+^^^^^^^^^^^^^^^^^^^^^^
+The ``trace_regex`` subcommand has been changed to take a file argument.
+Refer to :doc:`rec_control trace-regex <manpages/rec_control.1>` and :ref:`tracing` for details and example use.
 
 4.8.1 to 4.8.2
 --------------