-
- 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/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="stats">
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.</para>
<para>There are four types of statistics:
<itemizedlist>
<listitem>
- <simpara><emphasis>integer</emphasis> - this is the most common type. It
- is implemented as 64 bit integer (int64_t in C++), so it can hold any
+ <simpara><emphasis>integer</emphasis> - 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.</simpara>
</listitem>
<listitem>
<simpara><emphasis>floating point</emphasis> - 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.
</simpara>
</listitem>
<listitem>
<simpara><emphasis>duration</emphasis> - this type is intended for
recording time periods. It uses boost::posix_time::time_duration type,
- which stores hours, minutes, seconds and microseconds.</simpara>
+ which stores hours, minutes, seconds, and microseconds.</simpara>
</listitem>
<listitem>
<simpara><emphasis>string</emphasis> - this type is intended for
<para>
To extract data from the statistics module, the control channel can be
used. See <xref linkend="ctrl-channel"/> 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 <xref linkend="command-stats"/> for a list of
- statistic oriented commands.
+ statistics-oriented commands.
</para>
</section>
<title>Statistics Lifecycle</title>
<para>
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 <command>statistic-get-all</command> 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 <command>statistic-remove</command> or
- <command>statistic-remove-all</command> being called or the server is shut
- down. Per subnet statistics are explicitly removed when reconfiguration
+ <command>statistic-remove-all</command> being called, or when the server is shut
+ down. Per-subnet statistics are explicitly removed when reconfiguration
takes place.
</para>
<para>
- Statistics are considered run-time properties, so they are not retained
+ Statistics are considered runtime properties, so they are not retained
after server restart.
</para>
<para>
- 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 <command>statistic-remove</command> and
<command>statistic-remove-all</command> commands are intended to remove
<title>Commands for Manipulating Statistics</title>
<para>
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. <command>Remove</command> 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.
</para>
<note><para>
- 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 <xref linkend="ctrl-channel"/>.
</para></note>
<section xml:id="command-statistic-get">
- <title>statistic-get command</title>
+ <title>statistic-get Command</title>
<para>
- <emphasis>statistic-get</emphasis> command retrieves a single
- statistic. It takes a single string parameter called
- <command>name</command> that specifies the statistic name. An example
+ The <emphasis>statistic-get</emphasis> command retrieves a single
+ statistic. It takes a single-string parameter called
+ <command>name</command>, which specifies the statistic name. An example
command may look like this:
<screen>
{
</screen>
</para>
<para>
- 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).
</para>
</section> <!-- end of command-statistic-get -->
<section xml:id="command-statistic-reset">
- <title>statistic-reset command</title>
+ <title>statistic-reset Command</title>
<para>
- <emphasis>statistic-reset</emphasis> command sets the specified statistic
+ The <emphasis>statistic-reset</emphasis> 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 <command>name</command> that specifies the statistic name. An
+ duration, and "" for string type. It takes a single-string parameter
+ called <command>name</command>, which specifies the statistic name. An
example command may look like this:
<screen>
{
</screen>
</para>
<para>
- 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.
</para>
</section> <!-- end of command-statistic-reset -->
<section xml:id="command-statistic-remove">
- <title>statistic-remove command</title>
+ <title>statistic-remove Command</title>
<para>
- <emphasis>statistic-remove</emphasis> command attempts to delete a single
- statistic. It takes a single string parameter called
- <command>name</command> that specifies the statistic name. An example
+ The <emphasis>statistic-remove</emphasis> command attempts to delete a single
+ statistic. It takes a single-string parameter called
+ <command>name</command>, which specifies the statistic name. An example
command may look like this:
<screen>
{
</screen>
</para>
<para>
- 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.
</para>
</section> <!-- end of command-statistic-reset -->
<section xml:id="command-statistic-get-all">
- <title>statistic-get-all command</title>
+ <title>statistic-get-all Command</title>
<para>
- <emphasis>statistic-get-all</emphasis> command retrieves all statistics
+ The <emphasis>statistic-get-all</emphasis> command retrieves all statistics
recorded. An example command may look like this:
<screen>
{
</screen>
</para>
<para>
- 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).
</para>
</section> <!-- end of command-statistic-get-all -->
<section xml:id="command-statistic-reset-all">
- <title>statistic-reset-all command</title>
+ <title>statistic-reset-all Command</title>
<para>
- <emphasis>statistic-reset</emphasis> command sets all statistics to
+ The <emphasis>statistic-reset</emphasis> 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:
<screen>
{
"command": "statistic-reset-all",
</screen>
</para>
<para>
- 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.
</para>
</section> <!-- end of command-statistic-reset-all -->
<section xml:id="command-statistic-remove-all">
- <title>statistic-remove-all command</title>
+ <title>statistic-remove-all Command</title>
<para>
- <emphasis>statistic-remove-all</emphasis> command attempts to delete all
+ The <emphasis>statistic-remove-all</emphasis> command attempts to delete all
statistics. An example command may look like this:
<screen>
{
</screen>
</para>
<para>
- 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.
</para>
</section> <!-- end of command-statistic-remove-all -->
projects / thirdparty / kea.git / commitdiff
