1.. _hooks-stat-cmds:
2
3stat_cmds: Supplemental Statistics Commands
4===========================================
5
6This library provides additional commands for retrieving lease
7statistics from Kea DHCP servers. These commands were added to address
8an issue with obtaining accurate lease statistics in deployments running
9multiple Kea servers that use a shared lease backend. The in-memory
10statistics kept by individual servers only track lease changes made by
11that server; thus, in a deployment with multiple servers (e.g. two
12kea-dhcp6 servers using the same PostgreSQL database for lease storage),
13these statistics are incomplete. The MySQL and PostgreSQL backends in
14Kea track lease allocation changes as they occur via database triggers.
15Additionally, all four lease backends were extended to support
16retrieving lease statistics for all subnets, a single subnet, or a range
17of subnets. Finally, this library was constructed to provide commands
18for retrieving these statistics.
19
20.. note::
21
22   This library may only be loaded by the ``kea-dhcp4`` or
23   ``kea-dhcp6`` process.
24
25The commands currently provided by this library are:
26
27-  ``stat-lease4-get`` - fetches DHCPv4 lease statistics.
28
29-  ``stat-lease6-get`` - fetches DHCPv6 lease statistics.
30
31The stat commands library is part of the open source code and is
32available to every Kea user.
33
34All commands use JSON syntax and can be issued directly to the servers
35via either the control channel (see :ref:`ctrl-channel`) or the
36Control Agent (see :ref:`kea-ctrl-agent`).
37
38This library may be loaded by both the kea-dhcp4 and kea-dhcp6 servers. It
39is loaded in the same way as other libraries and currently has no
40parameters:
41
42::
43
44   "Dhcp6": {
45       "hooks-libraries": [
46           {
47               "library": "/path/libdhcp_stat_cmds.so"
48           }
49           ...
50       ]
51   }
52
53In a deployment with multiple Kea DHCP servers sharing a common lease
54storage, this hooks library may be loaded by any or all of the servers. However, one
55thing to keep in mind is that a server's response to a
56stat-lease[46]-get command will only contain data for subnets known to
57that server. In other words, if a subnet does not appear in a server's
58configuration, Kea will not retrieve statistics for it.
59
60.. _command-stat-lease4-get:
61
62.. _command-stat-lease6-get:
63
64The stat-lease4-get, stat-lease6-get Commands
65~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66
67The ``stat-lease4-get`` and ``stat-lease6-get`` commands fetch lease
68statistics for a range of known subnets. The range of subnets is
69determined through the use of optional command input parameters:
70
71-  ``subnet-id`` - the ID of the subnet for which lease statistics
72   should be fetched. Use this to get statistics for a single subnet. If
73   the subnet does not exist, the command result code is 3 (i.e.
74   CONTROL_RESULT_EMPTY).
75
76-  ``subnet-range`` - a pair of subnet IDs which describe an inclusive
77   range of subnets for which statistics should be retrieved. The range
78   may include one or more IDs that correspond to no subnet; in this
79   case, the command will only output lease statistics for those that
80   exist. However, if the range does not include any known subnets, the
81   command result code is 3 (i.e. CONTROL_RESULT_EMPTY).
82
83   -  ``first-subnet-id`` - the ID of the first subnet in the range.
84
85   -  ``last-subnet-id`` - the ID of the last subnet in the range.
86
87The use of subnet-id and subnet-range are mutually exclusive. If no
88parameters are given, the result will contain data for all known
89subnets. Note that in configurations with large numbers of subnets, this
90can result in a large response.
91
92The following command fetches lease statistics for all known subnets
93from a kea-dhcp4 server:
94
95::
96
97   {
98     "command": "stat-lease4-get"
99   }
100
101The following command fetches lease statistics for subnet ID 10 from a
102kea-dhcp6 server:
103
104::
105
106   {
107     "command": "stat-lease6-get",
108     "arguments": {
109       "subnet-id" : 10
110     }
111   }
112
113The following command fetches lease statistics for all subnets with IDs
114in the range 10 through 50 from a kea-dhcp4 server:
115
116::
117
118   {
119     "command": "stat-lease4-get",
120     "arguments": {
121       "subnet-range" {
122         "first-subnet-id": 10,
123         "last-subnet-id": 50,
124       }
125     }
126   }
127
128The response to either command will contain three elements:
129
130-  ``result`` - a numeric value indicating the outcome of the command
131   where:
132
133   -  ``0`` - the command was successful;
134
135   -  ``1`` - an error occurred, and an explanation will be the "text"
136      element; or
137
138   -  ``2`` - the fetch found no matching data.
139
140-  ``text`` - an explanation of the command outcome. When the command
141   succeeds it will contain the command name along with the number of
142   rows returned.
143
144-  ``arguments`` - a map containing the data returned by the command as
145   the element "result-set", which is patterned after SQL statement
146   responses:
147
148   -  ``columns`` - a list of text column labels. The columns returned
149      for DHCPv4 are:
150
151      -  ``subnet-id`` - the ID of the subnet.
152
153      -  ``total-addresses`` - the total number of addresses available for
154         DHCPv4 management in the subnet. In other words, this is the
155         sum of all addresses in all the configured pools in the subnet.
156
157      - ``cumulative-assigned-addresses`` - the cumulative number of addresses
158        in the subnet that have been assigned to a client by the server
159        since it started.
160
161      -  ``assigned-addresses`` - the number of addresses in the subnet that
162         are currently assigned to a client.
163
164      -  ``declined-addresses`` - the number of addresses in the subnet that
165         are currently declined and are thus unavailable for assignment.
166
167   -  The columns returned for DHCPv6 are:
168
169      -  ``subnet-id`` - the ID of the subnet.
170
171      -  ``total-nas`` - the number of NA addresses available for DHCPv6
172         management in the subnet. In other words, this is the sum of
173         all the NA addresses in all the configured NA pools in the
174         subnet.
175
176      - ``cumulative-assigned-nas`` - the cumulative number of NA addresses
177        in the subnet that have been assigned to a client by the server
178        since it started.
179
180      -  ``assigned-nas`` - the number of NA addresses in the subnet that
181         are currently assigned to a client.
182
183      -  ``declined-nas`` - the number of NA addresses that are currently
184         declined and are thus unavailable for assignment.
185
186      -  ``total-pds`` - the total number of PD prefixes available of DHCPv6
187         management in the subnet. In other words, this is the sum of
188         all prefixes in all the configured prefix pools in the subnet.
189
190      - ``cumulative-assigned-pds`` - the cumulative number of PD prefixes
191        in the subnet that have been assigned to a client by the server
192        since it started.
193
194      -  ``assigned-pds`` - the number of PD prefixes in the subnet that are
195         currently assigned to a client.
196
197   -  ``rows`` - a list of rows, one per subnet ID. Each row contains a
198      data value corresponding to and in the same order as each column
199      listed in "columns" for a given subnet.
200
201   -  ``timestamp`` - the textual date and time the data were fetched,
202      expressed as GMT.
203
204The response to a DHCPv4 command might look as follows:
205
206::
207
208     {
209       "result": 0,
210       "text": "stat-lease4-get: 2 rows found",
211       "arguments": {
212         "result-set": {
213           "columns": [ "subnet-id", "total-addresses", "cumulative-assigned-addresses", "assigned-addresses", "declined-addresses" ]
214           "rows": [
215             [ 10, 256, 300, 111, 0 ],
216             [ 20, 4098, 2034, 2034, 4 ]
217           ],
218         "timestamp": "2018-05-04 15:03:37.000000"
219         }
220       }
221     }
222
223The response to a DHCPv6 command might look as follows (subnet 10 has no
224prefix pools, subnet 20 has no NA pools, and subnet 30 has both NA and
225PD pools):
226
227::
228
229     {
230       "result": 0,
231       "text": "stat-lease6-get: 2 rows found",
232       "arguments": {
233         "result-set": {
234           "columns": [ "subnet-id", "total-nas", "cumulative-assigned-nas", "assigned-nas", "declined-nas", "total-pds", "cumulative-assigned-pds", "assigned-pds" ]
235           "rows": [
236             [ 10, 4096, 5000, 2400, 3, 0, 0, 0],
237             [ 20, 0, 0, 0, 0, 1048, 300, 233 ]
238             [ 30, 256, 60, 60, 0, 1048, 15, 15 ]
239           ],
240         "timestamp": "2018-05-04 15:03:37.000000"
241         }
242       }
243     }
244