mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-31 14:05:33 +00:00
Update stats.xml
This commit is contained in:
Suzanne Goldlust
committed by
Tomek Mrugalski
Tomek Mrugalski
parent
305415e057
commit
4541cd2ee7
@@ -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/.
|
||||
-->
|
||||
<!-- Converted by db4-upgrade version 1.1 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="stats">
|
||||
@@ -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.</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
|
||||
@@ -59,10 +59,10 @@
|
||||
<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>
|
||||
|
||||
@@ -70,22 +70,22 @@
|
||||
<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
|
||||
@@ -104,30 +104,30 @@
|
||||
<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>
|
||||
{
|
||||
@@ -139,22 +139,22 @@
|
||||
</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>
|
||||
{
|
||||
@@ -166,21 +166,21 @@
|
||||
</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>
|
||||
{
|
||||
@@ -192,19 +192,19 @@
|
||||
</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>
|
||||
{
|
||||
@@ -214,19 +214,19 @@
|
||||
</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",
|
||||
@@ -235,18 +235,18 @@
|
||||
</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>
|
||||
{
|
||||
@@ -256,9 +256,9 @@
|
||||
</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 -->
|
||||
|
||||
Reference in New Issue
Block a user