From 77d43b54250a733c4fab8163f5135b130a3d71f3 Mon Sep 17 00:00:00 2001 From: Remi Gacogne Date: Wed, 19 Jul 2017 14:35:25 +0200 Subject: [PATCH] dnsdist: Document sending statistics to carbon in the new docs --- pdns/dnsdistdist/docs/guides/carbon.rst | 45 ++++++++++++++++++++++ pdns/dnsdistdist/docs/guides/index.rst | 1 + pdns/dnsdistdist/docs/reference/carbon.rst | 11 ++++++ pdns/dnsdistdist/docs/reference/config.rst | 8 +++- pdns/dnsdistdist/docs/reference/index.rst | 1 + pdns/dnsdistdist/docs/statistics.rst | 33 +++++++++++++++- 6 files changed, 96 insertions(+), 3 deletions(-) create mode 100644 pdns/dnsdistdist/docs/guides/carbon.rst create mode 100644 pdns/dnsdistdist/docs/reference/carbon.rst diff --git a/pdns/dnsdistdist/docs/guides/carbon.rst b/pdns/dnsdistdist/docs/guides/carbon.rst new file mode 100644 index 000000000..7e07ee84e --- /dev/null +++ b/pdns/dnsdistdist/docs/guides/carbon.rst @@ -0,0 +1,45 @@ +Exporting statistics via Carbon +=============================== + +Setting up a carbon export +-------------------------- + +To emit metrics to Graphite, or any other software supporting the Carbon protocol, use:: + + carbonServer('ip-address-of-carbon-server', 'ourname', 30) + +Where ``ourname`` can be used to override your hostname, and ``30`` is the reporting interval in seconds. The last two arguments can be omitted. +The latest version of `PowerDNS Metronome `_ comes with attractive graphs for dnsdist by default. + +Query counters +-------------- + +In addition to other metrics, it is possible to send per-records statistics of the amount of queries by using :func:`setQueryCount`. With query counting enabled, dnsdist will increase a counter for every unique record or the behaviour you define in a custom Lua function by setting :func:`setQueryCountFilter`. This filter can decide whether to keep count on a query at all or rewrite for which query the counter will be increased. An example of a QueryCountFilter would be: + +.. code-block:: lua + + function filter(dq) + qname = dq.qname:toString() + + -- don't count PTRs at all + if(qname:match('in%-addr.arpa$')) then + return false, "" + end + + -- count these queries as if they were queried without leading www. + if(qname:match('^www.')) then + qname = qname:gsub('^www.', '') + end + + -- count queries by default + return true, qname + end + + setQueryCountFilter(filter) + +Valid return values for ``QueryCountFilter`` functions are: + +- true: count the specified query +- false: don't count the query + +Note that the query counters are buffered and flushed each time statistics are sent to the carbon server. The current content of the buffer can be inspected with ::func:`getQueryCounters`. If you decide to enable query counting without :func:`carbonServer`, make sure you implement clearing the log from ``maintenance()`` by issuing :func:`clearQueryCounters`. diff --git a/pdns/dnsdistdist/docs/guides/index.rst b/pdns/dnsdistdist/docs/guides/index.rst index 8654d61b0..c78e58150 100644 --- a/pdns/dnsdistdist/docs/guides/index.rst +++ b/pdns/dnsdistdist/docs/guides/index.rst @@ -12,4 +12,5 @@ These chapters contain several guides and nuggets of information regarding dnsdi downstreams serverpools serverselection + carbon diff --git a/pdns/dnsdistdist/docs/reference/carbon.rst b/pdns/dnsdistdist/docs/reference/carbon.rst new file mode 100644 index 000000000..1e3d49ac9 --- /dev/null +++ b/pdns/dnsdistdist/docs/reference/carbon.rst @@ -0,0 +1,11 @@ +Carbon export +============= + +.. function:: carbonServer(serverIP [, ourname], [interval]) + + Exort statistics to a Carbon / Graphite / Metronome server. + + :param string serverIP: Indicates the IP address where the statistics should be sent + :param string ourname: An optional string specifying the hostname that should be used + :param int interval: An optional unsigned integer indicating the interval in seconds between exports + diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst index 2a0869152..339691419 100644 --- a/pdns/dnsdistdist/docs/reference/config.rst +++ b/pdns/dnsdistdist/docs/reference/config.rst @@ -449,9 +449,13 @@ Status, Statistics and More Print a list of all allowed netmasks. +.. function:: showBinds() + + Print a list of all the current addresses and ports dnsdist is listening on, also called ``frontends`` + .. function:: showResponseLatency() - show a plot of the response time latency distribution + Show a plot of the response time latency distribution .. function:: showServers() @@ -473,7 +477,7 @@ Status, Statistics and More .. function:: showTCPStats() - show some statistics regarding TCP + Show some statistics regarding TCP .. function:: showVersion() diff --git a/pdns/dnsdistdist/docs/reference/index.rst b/pdns/dnsdistdist/docs/reference/index.rst index c751c9dfd..3b9ffa149 100644 --- a/pdns/dnsdistdist/docs/reference/index.rst +++ b/pdns/dnsdistdist/docs/reference/index.rst @@ -15,5 +15,6 @@ These chapters contain extensive information on all functions and object availab ebpf dnscrypt protobuf + carbon snmp tuning diff --git a/pdns/dnsdistdist/docs/statistics.rst b/pdns/dnsdistdist/docs/statistics.rst index 3279b0ce1..cb27a43b9 100644 --- a/pdns/dnsdistdist/docs/statistics.rst +++ b/pdns/dnsdistdist/docs/statistics.rst @@ -1,7 +1,14 @@ Statistics ========== -dnsdist keeps statistics on the queries is receives and send out. +dnsdist keeps statistics on the queries is receives and send out. They can be accessed in different ways: + +- via the console (see :ref:`Console`), using :func:`dumpStats` for the general ones, + :func:`showServers()` for the ones related to the backends, :func:`showBinds()` for the frontends, + `getPool("pool name"):getCache():printStats()` for the ones related to a specific cache and so on +- via the internal webserver (see :doc:`../guides/webserver`) +- via Carbon / Graphite / Metronome export (see :doc:`../guides/carbon`) +- via SNMP (see :doc:`../advanced/snmp`) acl-drops --------- @@ -25,21 +32,27 @@ Milliseconds spent by :program:`dnsdist` in the "user" state. downstream-send-errors ---------------------- +Number of errors when sending a query to a backend. downstream-timeouts ------------------- +Number of queries not answer in time by a backend. dyn-block-nmg-size ------------------ +Number of dynamic blocks entries. dyn-blocked ----------- +Number of queries dropped because of a dynamic block. empty-queries ------------- +Number of empty queries received from clients. fd-usage -------- +Number of currently used file descriptors. latency-avg100 -------------- @@ -59,30 +72,39 @@ Average response latency of the last 1000000 packets. latency-slow ------------ +Number of queries answered in more than 1 second. latency0-1 ---------- +Number of queries answered in less than 1 ms. latency1-10 ----------- +Number of queries answered in 1-10 ms. latency10-50 ------------ +Number of queries answered in 10-50 ms. latency50-100 ------------- +Number of queries answered in 50-100 ms. latency100-1000 --------------- +Number of queries answered in 100-1000 ms. no-policy --------- +Number of queries dropped because no server was available. noncompliant-queries -------------------- +Number of queries dropped as non-compliant. noncompliant-responses ---------------------- +Number of answers from a backend dropped as non-compliant. queries ------- @@ -94,28 +116,37 @@ Number of received queries with the recursion desired bit set. real-memory-usage ----------------- +Current memory usage. responses --------- +Number of responses received from backends. rule-drop --------- +Number of queries dropped because of a rule. rule-nxdomain ------------- +Number of NXDomain answers returned because of a rule. rule-refused ------------ +Number of Refused answers returned because of a rule. self-answered ------------- +Number of self-answered responses. servfail-responses ------------------ +Number of servfail answers received from backends. trunc-failures -------------- +Number of errors encountered while truncating an answer. uptime ------ +Uptime of the dnsdist process, in seconds. -- 2.40.0