"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"
---------------------
The PowerDNS Recursor exposes many :doc:`metrics <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 <manpages/rec_control.1>` 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.
+
+
projects / thirdparty / pdns.git / commitdiff
