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