1.. _mod-stats:
2
3``stats`` — Query statistics
4============================
5
6The module extends server statistics with incoming DNS request and corresponding
7response counters, such as used network protocol, total number of responded bytes,
8etc (see module reference for full list of supported counters).
9This module should be configured as the last module.
10
11.. NOTE::
12   Server initiated communication (outgoing NOTIFY, incoming \*XFR,...) is not
13   counted by this module.
14
15.. NOTE::
16   Leading 16-bit message size over TCP is not considered.
17
18Example
19-------
20
21Common statistics with default module configuration::
22
23    template:
24      - id: default
25        global-module: mod-stats
26
27Per zone statistics with explicit module configuration::
28
29    mod-stats:
30      - id: custom
31        edns-presence: on
32        query-type: on
33
34    template:
35      - id: default
36        module: mod-stats/custom
37
38Module reference
39----------------
40
41::
42
43 mod-stats:
44   - id: STR
45     request-protocol: BOOL
46     server-operation: BOOL
47     request-bytes: BOOL
48     response-bytes: BOOL
49     edns-presence: BOOL
50     flag-presence: BOOL
51     response-code: BOOL
52     request-edns-option: BOOL
53     response-edns-option: BOOL
54     reply-nodata: BOOL
55     query-type: BOOL
56     query-size: BOOL
57     reply-size: BOOL
58
59.. _mod-stats_id:
60
61id
62..
63
64A module identifier.
65
66.. _mod-stats_request-protocol:
67
68request-protocol
69................
70
71If enabled, all incoming requests are counted by the network protocol:
72
73* udp4 - UDP over IPv4
74* tcp4 - TCP over IPv4
75* udp6 - UDP over IPv6
76* tcp6 - TCP over IPv6
77* udp4-xdp - UDP over IPv4 through XDP
78* tcp4-xdp - TCP over IPv4 through XDP
79* udp6-xdp - UDP over IPv6 through XDP
80* tcp6-xdp - TCP over IPv6 through XDP
81
82*Default:* on
83
84.. _mod-stats_server-operation:
85
86server-operation
87................
88
89If enabled, all incoming requests are counted by the server operation. The
90server operation is based on message header OpCode and message query (meta) type:
91
92* query - Normal query operation
93* update - Dynamic update operation
94* notify - NOTIFY request operation
95* axfr - Full zone transfer operation
96* ixfr - Incremental zone transfer operation
97* invalid - Invalid server operation
98
99*Default:* on
100
101.. _mod-stats_request-bytes:
102
103request-bytes
104.............
105
106If enabled, all incoming request bytes are counted by the server operation:
107
108* query - Normal query bytes
109* update - Dynamic update bytes
110* other - Other request bytes
111
112*Default:* on
113
114.. _mod-stats_response-bytes:
115
116response-bytes
117..............
118
119If enabled, outgoing response bytes are counted by the server operation:
120
121* reply - Normal response bytes
122* transfer - Zone transfer bytes
123* other - Other response bytes
124
125.. WARNING::
126   Dynamic update response bytes are not counted by this module.
127
128*Default:* on
129
130.. _mod-stats_edns-presence:
131
132edns-presence
133.............
134
135If enabled, EDNS pseudo section presence is counted by the message direction:
136
137* request - EDNS present in request
138* response - EDNS present in response
139
140*Default:* off
141
142.. _mod-stats_flag-presence:
143
144flag-presence
145.............
146
147If enabled, some message header flags are counted:
148
149* TC - Truncated Answer in response
150* DO - DNSSEC OK in request
151
152*Default:* off
153
154.. _mod-stats_response-code:
155
156response-code
157.............
158
159If enabled, outgoing response code is counted:
160
161* NOERROR
162* ...
163* NOTZONE
164* BADVERS
165* ...
166* BADCOOKIE
167* other - All other codes
168
169.. NOTE::
170   In the case of multi-message zone transfer response, just one counter is
171   incremented.
172
173.. WARNING::
174   Dynamic update response code is not counted by this module.
175
176*Default:* on
177
178.. _mod-stats_request-edns-option:
179
180request-edns-option
181...................
182
183If enabled, EDNS options in requests are counted by their code:
184
185* CODE0
186* ...
187* EDNS-KEY-TAG (CODE14)
188* other - All other codes
189
190*Default:* off
191
192.. _mod-stats_response-edns-option:
193
194response-edns-option
195....................
196
197If enabled, EDNS options in responses are counted by their code. See
198:ref:`mod-stats_request-edns-option`.
199
200*Default:* off
201
202.. _mod-stats_reply-nodata:
203
204reply-nodata
205............
206
207If enabled, NODATA pseudo RCODE (:rfc:`2308#section-2.2`) is counted by the
208query type:
209
210* A
211* AAAA
212* other - All other types
213
214*Default:* off
215
216.. _mod-stats_query-type:
217
218query-type
219..........
220
221If enabled, normal query type is counted:
222
223* A (TYPE1)
224* ...
225* TYPE65
226* SPF (TYPE99)
227* ...
228* TYPE110
229* ANY (TYPE255)
230* ...
231* TYPE260
232* other - All other types
233
234.. NOTE::
235   Not all assigned meta types (IXFR, AXFR,...) have their own counters,
236   because such types are not processed as normal query.
237
238*Default:* off
239
240.. _mod-stats_query-size:
241
242query-size
243..........
244
245If enabled, normal query message size distribution is counted by the size range
246in bytes:
247
248* 0-15
249* 16-31
250* ...
251* 272-287
252* 288-65535
253
254*Default:* off
255
256.. _mod-stats_reply-size:
257
258reply-size
259..........
260
261If enabled, normal reply message size distribution is counted by the size range
262in bytes:
263
264* 0-15
265* 16-31
266* ...
267* 4080-4095
268* 4096-65535
269
270*Default:* off
271