From: Suzanne Goldlust Date: Mon, 31 Dec 2018 21:28:14 +0000 (-0500) Subject: Update stats.xml X-Git-Tag: 481-remote-subnet4-set-inconsistent-work-when-id-subnet-is-duplicated_base~51 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4541cd2ee701b360b028926d40bd9b0ef569a8ad;p=thirdparty%2Fkea.git Update stats.xml --- diff --git a/doc/guide/stats.xml b/doc/guide/stats.xml index 445cddf068..e7f7215776 100644 --- a/doc/guide/stats.xml +++ b/doc/guide/stats.xml @@ -3,7 +3,7 @@ - - This Source Code Form is subject to the terms of the Mozilla Public - License, v. 2.0. If a copy of the MPL was not distributed with this - - file, You can obtain one at http://mozilla.org/MPL/2.0/. + - file, you can obtain one at http://mozilla.org/MPL/2.0/. --> @@ -16,32 +16,32 @@ A working DHCP server encounters various events that can cause certain statistics to be collected. For example, a DHCPv4 server may receive a packet (pkt4-received - statistic increases by one) that after parsing was identified as a - DHCPDISCOVER (pkt4-discover-received). The Server processed it and - decided to send a DHCPOFFER representing its answer (pkt4-offer-sent + statistic increases by one) that after parsing is identified as a + DHCPDISCOVER (pkt4-discover-received). The server processes it and + decides to send a DHCPOFFER representing its answer (pkt4-offer-sent and pkt4-sent statistics increase 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 a server's and network's health. For example, - if pkt4-received statistic stops growing, it means that the + values in the high thousands. They can serve as an easy and powerful + tool for observing a server's and a network's health. For example, + if the 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 + integer - this is the most common type. It + is implemented as a 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. + store floating-point precision. It is implemented as double C++ type. duration - this type is intended for recording time periods. It uses boost::posix_time::time_duration type, - which stores hours, minutes, seconds and microseconds. + which stores hours, minutes, seconds, and microseconds. string - this type is intended for @@ -59,10 +59,10 @@ To extract data from the statistics module, the control channel can be used. See for details. It is possible to - retrieve a single or all statistics, reset statistics (i.e. set to neutral - value, typically zero) or even remove completely a single or all + retrieve a single statistic or all statistics, reset statistics (i.e. set to neutral + value, typically zero), or even remove completely a single statistic or all statistics. See section for a list of - statistic oriented commands. + statistics-oriented commands. @@ -70,22 +70,22 @@ Statistics Lifecycle It is useful to understand how the Statistics Manager module works. When - the server starts operation, the manager is empty and does not have any + the server starts operation, the manager is empty and contains no statistics. When statistic-get-all is executed, an empty list is returned. Once the server performs an operation that causes - a statistic to change, the related statistic will be created. In the general - case, once a statistic is recorded even once, it is kept in the manager, until + a statistic to change, the related statistic will be created. In general, + once a statistic is recorded even once, it is kept in the manager until explicitly removed, by statistic-remove or - statistic-remove-all being called or the server is shut - down. Per subnet statistics are explicitly removed when reconfiguration + statistic-remove-all being called, or when 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 + Statistics are considered runtime properties, so they are not retained after server restart. - Removing a statistic that is updated frequently makes little sense as it + Removing a statistic that is updated frequently makes little sense, as it will be re-added when the server code next records that statistic. The statistic-remove and statistic-remove-all commands are intended to remove @@ -104,30 +104,30 @@ 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 + resetting to zero or neutral value (-reset), or even removing a statistic completely (-remove). The difference between reset and remove is somewhat - subtle. The reset command sets the value of the statistic to zero or neutral - value. After this operation, the statistic will have a value of 0 (integer), - 0.0 (float), 0h0m0s0us (duration) or "" (string). When asked for, a statistic + subtle. The reset command sets the value of the statistic to zero or a neutral + value, so after this operation, the statistic will have a value of 0 (integer), + 0.0 (float), 0h0m0s0us (duration), or "" (string). When requested, a statistic with the values mentioned will be returned. Remove removes a statistic completely, so the statistic will not be reported anymore. Please - note that the server code may add it back if there's a reason to record + note that the server code may add it back if there is a reason to record it. - The following sections describe commands that can be sent to the server: the - examples are not fragments of a configuration file. For more information on + The following sections describe commands that can be sent to the server; the + examples are not fragments of a configuration file. For more information on sending commands to Kea, see .
- statistic-get command + 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 + The statistic-get command retrieves a single + statistic. It takes a single-string parameter called + name, which specifies the statistic name. An example command may look like this: { @@ -139,22 +139,22 @@ - The server will respond with details of the requested statistic, with result - set to 0 indicating success and the specified statistic as the value of + The server returns details of the requested statistic, with a result + of 0 indicating success and the specified statistic as the value of the "arguments" parameter. If the 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). + will contain an empty map, i.e. only { } as an argument, but the status + code will still indicate success (0).
- statistic-reset command + statistic-reset Command - statistic-reset command sets the specified statistic + The statistic-reset command sets the 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 + duration, and "" for string type. It takes a single-string parameter + called name, which specifies the statistic name. An example command may look like this: { @@ -166,21 +166,21 @@ - If the specific statistic is found and reset was successful, the - server will respond with a status of 0, indicating success and an empty - parameters field. If an error is encountered (e.g. requested statistic - was not found), the server will return a status code of 1 (error) - and the text field will contain the error description. + If the specific statistic is found and the reset is successful, the + server responds with a status of 0, indicating success, and an empty + parameters field. If an error is encountered (e.g. the requested statistic + was not found), the server returns a status code of 1 (error) + and the text field contains the error description.
- statistic-remove command + statistic-remove Command - statistic-remove command attempts to delete a single - statistic. It takes a single string parameter called - name that specifies the statistic name. An example + The statistic-remove command attempts to delete a single + statistic. It takes a single-string parameter called + name, which specifies the statistic name. An example command may look like this: { @@ -192,19 +192,19 @@ - If the specific statistic is found and its removal was successful, the - server will respond with a status of 0, indicating success and an empty - parameters field. If an error is encountered (e.g. requested statistic - was not found), the server will return a status code of 1 (error) - and the text field will contain the error description. + If the specific statistic is found and its removal is successful, the + server responds with a status of 0, indicating success, and an empty + parameters field. If an error is encountered (e.g. the requested statistic + was not found), the server returns a status code of 1 (error) + and the text field contains the error description.
- statistic-get-all command + statistic-get-all Command - statistic-get-all command retrieves all statistics + The statistic-get-all command retrieves all statistics recorded. An example command may look like this: { @@ -214,19 +214,19 @@ - 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 server responds with details of all recorded statistics, with a result + set to 0 to indicate that it iterated over all statistics (even when the total number of statistics is zero).
- statistic-reset-all command + statistic-reset-all Command - statistic-reset command sets all statistics to + The 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: + duration, and "" for string type. An example command may look like this: { "command": "statistic-reset-all", @@ -235,18 +235,18 @@ - If the operation is successful, the server will respond with a status of - 0, indicating success and an empty parameters field. If an error is - encountered, the server will return a status code of 1 (error) and the text - field will contain the error description. + If the operation is successful, the server responds with a status of + 0, indicating success, and an empty parameters field. If an error is + encountered, the server returns a status code of 1 (error) and the text + field contains the error description.
- statistic-remove-all command + statistic-remove-all Command - statistic-remove-all command attempts to delete all + The statistic-remove-all command attempts to delete all statistics. An example command may look like this: { @@ -256,9 +256,9 @@ - If the removal of all statistics was successful, the server will respond - with a status of 0, indicating success and an empty parameters field. If - an error is encountered, the server will return a status code of 1 (error) + If the removal of all statistics is successful, the server responds + with a status of 0, indicating success, and an empty parameters field. If + an error is encountered, the server returns a status code of 1 (error) and the text field will contain the error description.