From: Otto Date: Mon, 23 Aug 2021 10:07:08 +0000 (+0200) Subject: Docs for event tracing X-Git-Tag: dnsdist-1.7.0-alpha2~9^2~9 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=503d207ff2d3dc8f1481ab4896280b6707effd8d;p=thirdparty%2Fpdns.git Docs for event tracing --- diff --git a/.github/actions/spell-check/expect.txt b/.github/actions/spell-check/expect.txt index 09f91df683..c7ec3d96ef 100644 --- a/.github/actions/spell-check/expect.txt +++ b/.github/actions/spell-check/expect.txt @@ -1202,6 +1202,7 @@ pathconfig pathto pawal Pbackend +PCache pcap PCAPFILE pdf diff --git a/pdns/rec_channel_rec.cc b/pdns/rec_channel_rec.cc index dbc3a15355..529f7ad729 100644 --- a/pdns/rec_channel_rec.cc +++ b/pdns/rec_channel_rec.cc @@ -1954,7 +1954,7 @@ RecursorControlChannel::Answer RecursorControlParser::getAnswer(int s, const str "set-minimum-ttl value set minimum-ttl-override\n" "set-carbon-server set a carbon server for telemetry\n" "set-dnssec-log-bogus SETTING enable (SETTING=yes) or disable (SETTING=no) logging of DNSSEC validation failures\n" -"set-event-trace-enabled SETTING set logging of event trace messages, 0 = disabled, 1 = prottobuf, 2 = log file, 3 = both\n" +"set-event-trace-enabled SETTING set logging of event trace messages, 0 = disabled, 1 = protobuf, 2 = log file, 3 = both\n" "trace-regex [regex] emit resolution trace for matching queries (empty regex to clear trace)\n" "top-largeanswer-remotes show top remotes receiving large answers\n" "top-queries show top queries\n" diff --git a/pdns/recursordist/docs/manpages/rec_control.1.rst b/pdns/recursordist/docs/manpages/rec_control.1.rst index 7bd6b857a1..eda01c07fb 100644 --- a/pdns/recursordist/docs/manpages/rec_control.1.rst +++ b/pdns/recursordist/docs/manpages/rec_control.1.rst @@ -218,6 +218,9 @@ set-max-packetcache-entries *NUM* set-minimum-ttl *NUM* Set minimum-ttl-override to *NUM*. +set-event-trace-enabled *NUM* + Set logging of event trace messages, 0 = disabled, 1 = protobuf, 2 = log file, 3 = both. + top-queries Shows the top-20 queries. Statistics are over the last 'stats-ringbuffer-entries' queries. diff --git a/pdns/recursordist/docs/performance.rst b/pdns/recursordist/docs/performance.rst index d9e415e1c6..1040b711b9 100644 --- a/pdns/recursordist/docs/performance.rst +++ b/pdns/recursordist/docs/performance.rst @@ -193,3 +193,104 @@ Measuring performance --------------------- The PowerDNS Recursor exposes many :doc:`metrics ` that can be graphed and monitored. + +Event Tracing +------------- +Event tracing is an experimental feature introduced in version 4.6.0 that allows following the internals of processing queries in more detail. + +In certain spots in the resolving process event records are created that contain an identification of the event, a timestamp, potentially a value and an indication if this was the start or the end of an event. This is relevant for events that describe stages in the resolving process. + +At this point in time event logs of queries can be exported using a protobuf log or they can be written to the log file. + +Note that this is an experimental feature that will change in upcoming releases. + +Currently, an event protobuf message has the following definition: + +.. code-block:: protobuf + + enum EventType { + RecRecv = 1; + DistPipe = 2; + PCacheCheck = 3; + SyncRes = 4; + AnswerSent = 5; + LuaGetTag = 100; + LuaGetTagFFI = 101; + LuaIPFilter = 102; + LuaPreRPZ = 103; + LuaPreResolve = 104; + LuaPreOutQuery = 105; + LuaPostResolve = 106; + LuaNoData = 107; + LuaNXDomain = 108; + } + +.. code-block:: protobuf + + message Event { + required uint64 ts = 1; + required EventType event = 2; + required bool start = 3; + optional bool boolVal = 4; + optional int64 intVal = 5; + optional string stringVal = 6; + optional bytes bytesVal = 7; + } + repeated Event trace = 23; + +Event traces can be enabled by either setting :ref:`setting-event-trace-enabled` or by using the :doc:`rec_control ` subcommand ``set-event-trace-enabled``. + +An example of a trace (timestamps are relative in nanoseconds): + +.. code-block:: C + + - RecRecv(70); + - PCacheCheck(411964); + - PCacheCheck(416783,0,done); + - SyncRes(441811); + - SyncRes(337233971,0,done); + -AnswerSent(337266453) + +The packet cache check event has two events. +The first signals the start of packet cache lookup, and the second the completion of the packet cache lookup with result 0 (not found). +The SynRec event also has two entries. The value (0) is the return value of the SyncRes function. + +An example of a trace with a packet cache hit): + +.. code-block:: C + + - RecRecv(60); + - PCacheCheck(22913); + - PCacheCheck(113255,1,done); + - AnswerSent(117493) + +Here it can be seen that packet cache returns 1 (found). + +An example where various Lua related events can be seen: + +.. code-block:: C + + RecRecv(150); + PCacheCheck(26912); + PCacheCheck(51308,0,done); + LuaIPFilter(56868); + LuaIPFilter(57149,0,done); + LuaPreRPZ(82728); + LuaPreRPZ(82918,0,done); + LuaPreResolve(83479); + LuaPreResolve(210621,0,done); + SyncRes(217424); + LuaPreOutQuery(292868); + LuaPreOutQuery(292938,0,done); + LuaPreOutQuery(24702079); + LuaPreOutQuery(24702349,0,done); + LuaPreOutQuery(43055303); + LuaPreOutQuery(43055634,0,done); + SyncRes(80470320,0,done); + LuaPostResolve(80476592); + LuaPostResolve(80476772,0,done); + AnswerSent(80500247) + +There is no packet cache hit, so SyncRes is called which does a couple of outgoing queries. + + diff --git a/pdns/recursordist/docs/settings.rst b/pdns/recursordist/docs/settings.rst index fa637ecd22..621dbfd40c 100644 --- a/pdns/recursordist/docs/settings.rst +++ b/pdns/recursordist/docs/settings.rst @@ -706,6 +706,18 @@ Change to ``/dev/random`` if PowerDNS should block waiting for enough entropy to The path to the /etc/hosts file, or equivalent. This file can be used to serve data authoritatively using `export-etc-hosts`_. +.. _setting-event-trace-enabled: + +``event-trace-enabled`` +----------------------- +.. versionadded:: 4.6.0 + +- Integer +- Default: 0 + +Enable the recording and logging of ref:`event traces`. This is an experimental feature subject to change. +Possible values are 0: (disabled), 1 (add information to protobuf logging messages) and 2 (write to log) and 3 (both). + .. _setting-export-etc-hosts: ``export-etc-hosts``