From: Tomek Mrugalski Date: Thu, 18 Jun 2015 15:15:40 +0000 (+0200) Subject: [3800] 6 statistic-{get,reset,remove}-* commands described. X-Git-Tag: trac3910_base~6^2~3 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a88383d5ed9e8eac7327faa1c6b894c7abbfefec;p=thirdparty%2Fkea.git [3800] 6 statistic-{get,reset,remove}-* commands described. --- diff --git a/doc/guide/stats.xml b/doc/guide/stats.xml index 9f907c3713..9d59f861e2 100644 --- a/doc/guide/stats.xml +++ b/doc/guide/stats.xml @@ -4,30 +4,257 @@ ]> - - Statistics
Statistics Overview - + + Both Kea DHCP servers support statistics gathering since + 0.9.2-beta version. Working DHCP server encounters various events + that can influence certain statistics to be collected. For + example, a DHCPv4 server may receive a packet (pkt4-received + statistic increased by one) that after parsing was identifier as + DHCPDISCOVER (pkt4-discover-received). Server processed it and + decided to send DHCPOFFER representing its answer (pkt4-offer-sent + and pkt4-sent statistics increased by one). Such events happen + frequently, so it is not uncommon for the statistics to have + values in high thousands. They can serve as an easy and powerful + tool for observing server's and network's health. For example, + if pkt4-received statistic stops growing, it means that the + clients' packets are not reaching the server. + + There are four types of statistics: + + + integer - this is the most common type. It + is implemented as 64 bit integer (int64_t in C++), so it can hold any + value between -2^63 to 2^63 -1. + + + floating point - this type is intended to + store floating point precision. It is implemented as double C++ type. + + + + duration - this type is intended for + recoding time periods. It uses boost::posix_time::time_duration type, + which stores hours, minutes, seconds and microseconds. + + + string - this type is intended for + recoding statistics in textual forma. It uses std::string C++ type. + + + + + - TODO: Describe statistics collection here as part of ticket #3800. - For DHCPv4 specific statistics, see . - For DHCPv6 specific statistics, see TODO. - For DDNS specific statistics, see TODO. + During normal operation, DHCPv4 and DHCPv6 servers gather statistics. + For a DHCPv4 and DHCPv6 list of statistics, see and , respectively. + + + + To extract data from the statistics module, the control channel can be + used. See for details. It is possible to + retrieve a single statistic, all statistics, reset (i.e. set to neutral + value, typically zero) or even remove completely a single or all + statistics. See section for a list of + statistic oriented commands.
- +
+ Statistics Lifecycle + + It is useful to understand how Statistics Manager module is working. When + the server starts operation, the manager is empty and does not have any + statistics. When statistic-get-all is executed, an + empty list is returned. Once the server performs an operation that causes + statistic change, related statistic will be created. In a general case + once a statistic is recorded even once, it is kept in the manager, until + explicitly removed, by statistic-remove or + statistic-remove-all is called or the server is shut + down. Per subnet statistics are explicitly removed when reconfiguration + takes place. + + + Statistics are considered run-time properties, so they are not retained + after server restart. + + + Removing a statistic that is updated frequently makes little sense as it + will be re-added when the server code records a given statistic the next + time. statistic-remove and + statistic-remove-all commands are intended to remove + statistics that is not expected to be observed in the near future. For + example, a misconfigured device in a network may cause clients to report + duplicate addresses, so the server will report increasing values of + pkt4-decline-received. Once the problem is found and the device is + removed, system administrator may want to remove pkt4-decline-received + statistic, so it won't be reported anymore. If duplicate address is + detected ever again, the server will add this statistic back. + +
+ +
+ Commands for manipulating statistics + + There are several commands defined that can be used for accessing (-get), + resetting to zero or neutral value (-reset) or even removing a statistic + completely (-remove). The difference between reset and remove is somewhat + subtle. Reset command sets value of the statistic to zero or neutral + value. After this operation, statistic will have value of 0 (integer), 0.0 + (float), 0h0m0s0us (duration) or "" (string). When asked for, statistic + with the values metioned will be returned. Remove removes a statistic + completely, so the statistic will not be reported anymore. Please note + that + + +
+ statistic-get command + + + statistic-get command retrieves a single + statistic. It takes a single string parameter called + name that specifies the statistic name. An example + command may look like this: + +{ + "command": "statistic-get", + "arguments": { + "name": "pkt4-received" + } +} + + + + The server will respond with details of requested statistic, with result + set to 0 indicates success and specified statistic as the value of + "arguments" parameter. If requested statistic is not found, the response + will contain an empty map, i.e. only { } as argument, but the status + code will still be set to success (0). + +
+ +
+ statistic-reset command + + + statistic-reset command sets specified statistic to + its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time + duration and "" for string type. It takes a single string parameter + called name that specifies the statistic name. An + example command may look like this: + +{ + "command": "statistic-reset", + "arguments": { + "name": "pkt4-received" + } +} + + + + If specific statistic is found and reset was successful, + the server will respond with status of 0, indicating success and empty + parameters field. If error is encountered (e.g. requested statistic + was not found), the server will return status code of 1 (error) + and text field will contain the error description. + +
+ +
+ statistic-remove command + + + statistic-remove command attempt to delete a single + statistic. It takes a single string parameter called + name that specifies the statistic name. An example + command may look like this: + +{ + "command": "statistic-remove", + "arguments": { + "name": "pkt4-received" + } +} + + + + If specific statistic is found and its removal was successful, + the server will respond with status of 0, indicating success and empty + parameters field. If error is encountered (e.g. requested statistic + was not found), the server will return status code of 1 (error) + and text field will contain the error description. + +
+ +
+ statistic-get-all command + + + statistic-get-all command retrieves a single + statistic. An example + command may look like this: + +{ + "command": "statistic-get-all", + "arguments": { } +} + + + + The server will respond with details of all recorded statistics, with result + set to 0 indicating that it iterated over all statistics (even when + the total number of statistics is zero). + +
+ +
+ statistic-reset-all command + + + statistic-reset command sets all statistics to + their neutral values: 0 for integer, 0.0 for float, 0h0m0s0us for time + duration and "" for string type. An example command may look like this: + +{ + "command": "statistic-reset-all", + "arguments": { } +} + + + + If the operation is successful, the server will respond with status of + 0, indicating success and empty parameters field. If error is + encountered, the server will return status code of 1 (error) and text + field will contain the error description. + +
+ +
+ statistic-remove-all command + + + statistic-remove-all command attempt to delete all + statistics. An example command may look like this: + +{ + "command": "statistic-remove-all", + "arguments": { } +} + + + + If removal of all statistics was successful, the server will respond + with status of 0, indicating success and empty parameters field. If + error is encountered, the server will return status code of 1 (error) + and text field will contain the error description. + +
+ +
+ +