1 files changed, 274 insertions, 0 deletions
diff --git a/src/knot/modules/stats/stats.rst b/src/knot/modules/stats/stats.rst
new file mode 100644
index 0000000..8acf1aa
--- /dev/null
+++ b/src/knot/modules/stats/stats.rst
@@ -0,0 +1,274 @@
+.. _mod-stats:
+
+``stats`` — Query statistics
+============================
+
+The module extends server statistics with incoming DNS request and corresponding
+response counters, such as used network protocol, total number of responded bytes,
+etc (see module reference for full list of supported counters).
+This module should be configured as the last module.
+
+.. NOTE::
+   Server initiated communication (outgoing NOTIFY, incoming \*XFR,...) is not
+   counted by this module.
+
+.. NOTE::
+   Leading 16-bit message size over TCP is not considered.
+
+Example
+-------
+
+Common statistics with default module configuration::
+
+    template:
+      - id: default
+        global-module: mod-stats
+
+Per zone statistics with explicit module configuration::
+
+    mod-stats:
+      - id: custom
+        edns-presence: on
+        query-type: on
+
+    template:
+      - id: default
+        module: mod-stats/custom
+
+Module reference
+----------------
+
+::
+
+ mod-stats:
+   - id: STR
+     request-protocol: BOOL
+     server-operation: BOOL
+     request-bytes: BOOL
+     response-bytes: BOOL
+     edns-presence: BOOL
+     flag-presence: BOOL
+     response-code: BOOL
+     request-edns-option: BOOL
+     response-edns-option: BOOL
+     reply-nodata: BOOL
+     query-type: BOOL
+     query-size: BOOL
+     reply-size: BOOL
+
+.. _mod-stats_id:
+
+id
+..
+
+A module identifier.
+
+.. _mod-stats_request-protocol:
+
+request-protocol
+................
+
+If enabled, all incoming requests are counted by the network protocol:
+
+* udp4 - UDP over IPv4
+* tcp4 - TCP over IPv4
+* quic4 - QUIC over IPv4
+* udp6 - UDP over IPv6
+* tcp6 - TCP over IPv6
+* quic6 - QUIC over IPv6
+* udp4-xdp - UDP over IPv4 through XDP
+* tcp4-xdp - TCP over IPv4 through XDP
+* quic4-xdp - QUIC over IPv4 through XDP
+* udp6-xdp - UDP over IPv6 through XDP
+* tcp6-xdp - TCP over IPv6 through XDP
+* quic6-xdp - QUIC over IPv6 through XDP
+
+*Default:* ``on``
+
+.. _mod-stats_server-operation:
+
+server-operation
+................
+
+If enabled, all incoming requests are counted by the server operation. The
+server operation is based on message header OpCode and message query (meta) type:
+
+* query - Normal query operation
+* update - Dynamic update operation
+* notify - NOTIFY request operation
+* axfr - Full zone transfer operation
+* ixfr - Incremental zone transfer operation
+* invalid - Invalid server operation
+
+*Default:* ``on``
+
+.. _mod-stats_request-bytes:
+
+request-bytes
+.............
+
+If enabled, all incoming request bytes are counted by the server operation:
+
+* query - Normal query bytes
+* update - Dynamic update bytes
+* other - Other request bytes
+
+*Default:* ``on``
+
+.. _mod-stats_response-bytes:
+
+response-bytes
+..............
+
+If enabled, outgoing response bytes are counted by the server operation:
+
+* reply - Normal response bytes
+* transfer - Zone transfer bytes
+* other - Other response bytes
+
+.. WARNING::
+   Dynamic update response bytes are not counted by this module.
+
+*Default:* ``on``
+
+.. _mod-stats_edns-presence:
+
+edns-presence
+.............
+
+If enabled, EDNS pseudo section presence is counted by the message direction:
+
+* request - EDNS present in request
+* response - EDNS present in response
+
+*Default:* ``off``
+
+.. _mod-stats_flag-presence:
+
+flag-presence
+.............
+
+If enabled, some message header flags are counted:
+
+* TC - Truncated Answer in response
+* DO - DNSSEC OK in request
+
+*Default:* ``off``
+
+.. _mod-stats_response-code:
+
+response-code
+.............
+
+If enabled, outgoing response code is counted:
+
+* NOERROR
+* ...
+* NOTZONE
+* BADVERS
+* ...
+* BADCOOKIE
+* other - All other codes
+
+.. NOTE::
+   In the case of multi-message zone transfer response, just one counter is
+   incremented.
+
+.. WARNING::
+   Dynamic update response code is not counted by this module.
+
+*Default:* ``on``
+
+.. _mod-stats_request-edns-option:
+
+request-edns-option
+...................
+
+If enabled, EDNS options in requests are counted by their code:
+
+* CODE0
+* ...
+* EDNS-KEY-TAG (CODE14)
+* other - All other codes
+
+*Default:* ``off``
+
+.. _mod-stats_response-edns-option:
+
+response-edns-option
+....................
+
+If enabled, EDNS options in responses are counted by their code. See
+:ref:`mod-stats_request-edns-option`.
+
+*Default:* ``off``
+
+.. _mod-stats_reply-nodata:
+
+reply-nodata
+............
+
+If enabled, NODATA pseudo RCODE (:rfc:`2308#section-2.2`) is counted by the
+query type:
+
+* A
+* AAAA
+* other - All other types
+
+*Default:* ``off``
+
+.. _mod-stats_query-type:
+
+query-type
+..........
+
+If enabled, normal query type is counted:
+
+* A (TYPE1)
+* ...
+* TYPE65
+* SPF (TYPE99)
+* ...
+* TYPE110
+* ANY (TYPE255)
+* ...
+* TYPE260
+* other - All other types
+
+.. NOTE::
+   Not all assigned meta types (IXFR, AXFR,...) have their own counters,
+   because such types are not processed as normal query.
+
+*Default:* ``off``
+
+.. _mod-stats_query-size:
+
+query-size
+..........
+
+If enabled, normal query message size distribution is counted by the size range
+in bytes:
+
+* 0-15
+* 16-31
+* ...
+* 272-287
+* 288-65535
+
+*Default:* ``off``
+
+.. _mod-stats_reply-size:
+
+reply-size
+..........
+
+If enabled, normal reply message size distribution is counted by the size range
+in bytes:
+
+* 0-15
+* 16-31
+* ...
+* 4080-4095
+* 4096-65535
+
+*Default:* ``off``