This page documents requirements for the statistics implementation in Kea servers.
See design page for a design that is expected to fulfill those requirements.
The status of this document it a bit unusual. The original design was implemented in 0.9.2. However, new expectations appeared and we kicked of GSOC project in 2019. Depending on the pace of development, we expect some of the changes to make it into 1.6, but in general the majority is expected in 1.7.
Use case 1: The server maintains counters for received and sent packets, one for each packet type. Those are queried periodically, e.g. every 5 minutes, by an external system to monitor the server health. In particular, increasing number of NAKs is a sign of troubles.
Use case 2: The same as 1, but the counters are reset after each read.
Use case 3: Certain property of the server is being investigated. One specific metric (e.g. malformed packets received in subnet X) is being observed frequently, e.g. every 2 seconds.
Use case 4: All server statistics are dumped once per hour.
Use case 5: Server monitoring is integrated with network monitoring tool, like Nagios or MRTG. Small number of statistics are selected. They are polled every 5 minutes and the monitoring software generates graphs for it.
General Kea servers:
MUST be able to store the following types: integer values (64-bits), floating (double precision), timestamp, time.
Time related values SHOULD have precision better than seconds.
MUST be able to store values (setCounter("foo", 5) will set a given statistic to 5)
MUST be able to work in additive mode (addCounter("foo", 5) will add 5 to the current value of the statistic)
SHOULD be able to generate statistics over time (e.g. how much a given statistic had changed over last 10 seconds, last 5 minutes, last hour)
MUST be able to handle global statistics
MUST be able to handle statistics on a per scope basis. The only supported scope for 0.9.2 is subnet, but other scopes will likely to be added in the future (e.g. host scope that gathers statistics for each host separately)
MUST be able to retrieve a value of a single statistic
MUST be able to retrieve values of all statistics
MUST be able to reset a single statistic
MUST be able to reset all statistics
MAY be able to keep the statistics after server restart (not planned for 0.9.2, but may appear eventually in future releases)
MUST be easily extensible (with new counters)
Adding statistics in existing code MUST be easy to do (preferably a single call without any complex getters, accessors and intermediate objects)
MUST be usable in hooks libraries.
(removed) MUST be able to report combinations of existing metrics (e.g. pool_utilization = assigned / total). The supported operations are + (addition), - (subtraction), * (multiplication), /(division). (after discussion this capability was removed, it can be achieved by an external script, so it unnecessarily degrade performance).
MUST be possible to report or pool for a given statistic or statistics periodically, even when there's no incoming traffic. Either pooling (i.e. external trigger requests a statistic) or reporting (i.e. the server does timing on its own and reports periodically) is need, not both.
DHCPv4 MUST report the number of packets of each type received and sent (separate statistic for DISCOVER, OFFER, REQUEST, ACK etc.)
DHCPv6 MUST report the number of packets of each type received and sent (separate statistic for SOLICIT, ADVERTISE, REQUEST, REPLY etc.)
DHCPV4/6 MUST be able to report number of assigned and released addresses for each subnet
DHCPV4/6 MUST be able to report number of total addresses in the pool for each subnet
DHCPV4/6 MUST be able to report how many times an address was assigned based on host reservation
DHCPV4/6 MUST be able to report the number of times an incoming packet was dropped.
DHCPv4/6 MUST be able to report the number of times the code received an option it couldn't parse (malformed options)
DHCPv4/6 MUST report how many add and delete Name Change Requests it issued to the D2 module
D2 MUST report how many Name Change Requests it received from the DHCP servers
D2 MUST report how many DNS Updates it sent to the DNS servers
D2 MUST report how many successful/failed DNS Updates it completed