dnsdist: Document sending statistics to carbon in the new docs

diff --git a/pdns/dnsdistdist/docs/guides/carbon.rst b/pdns/dnsdistdist/docs/guides/carbon.rst
new file mode 100644 (file)
index 0000000..7e07ee8
--- /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 <https://github.com/ahupowerdns/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 8654d61b0305428b80ef079baee9f8fe332a12f7..c78e58150b6c7d6b1c3c50efe58a52e0fc2bc4d8 100644 (file)
--- 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 (file)
index 0000000..1e3d49a
--- /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 2a0869152ab9487bc454021344df582fa43538e5..3396914190580c2c8cb1ad5b4bde7b4d63bfeea7 100644 (file)
--- 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 c751c9dfd32ef3e8e7a90ff8a6fb19aa9b3d6d0c..3b9ffa1491b27d2907ee0355d2d7cebc1eb21a93 100644 (file)
--- 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 3279b0ce1ec4335d4b06f421bc81f4155b6f655c..cb27a43b96bd350b947d939f44914148038f362e 100644 (file)
--- 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.