Commit a88383d5 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[3800] 6 statistic-{get,reset,remove}-* commands described.

parent c3346812
......@@ -4,30 +4,257 @@
<!ENTITY mdash "&#x2014;" >
]>
<!-- Note: Please use the following terminology:
- daemon - one process (e.g. kea-dhcp4)
- component - one piece of code within a daemon (e.g. libdhcp or hooks)
- server - currently equal to daemon, but the difference will be more
prominent once we add client or relay support
- logger - one instance of isc::log::Logger
- structure - an element in config file (e.g. "Dhcp4")
Do not use:
- module => daemon
-->
<chapter id="stats">
<title>Statistics</title>
<section>
<title>Statistics Overview</title>
<para>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.</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
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.
</simpara>
</listitem>
<listitem>
<simpara><emphasis>duration</emphasis> - this type is intended for
recoding time periods. It uses boost::posix_time::time_duration type,
which stores hours, minutes, seconds and microseconds.</simpara>
</listitem>
<listitem>
<simpara><emphasis>string</emphasis> - this type is intended for
recoding statistics in textual forma. It uses std::string C++ type.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
TODO: Describe statistics collection here as part of ticket #3800.
For DHCPv4 specific statistics, see <xref linkend="dhcp4-stats"/>.
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 <xref
linkend="dhcp4-stats"/> and <xref linkend="dhcp6-stats"/>, respectively.
</para>
<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 statistic, all statistics, reset (i.e. set to neutral
value, typically zero) or even remove completely a single or all
statistics. See section <xref linkend="command-stats"/> for a list of
statistic oriented commands.
</para>
</section>
</chapter>
<section id="stats-lifecycle">
<title>Statistics Lifecycle</title>
<para>
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 <command>statistic-get-all</command> 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 <command>statistic-remove</command> or
<command>statistic-remove-all</command> is called or 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
after server restart.
</para>
<para>
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. <command>statistic-remove</command> and
<command>statistic-remove-all</command> 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.
</para>
</section>
<section id="command-stats">
<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
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
</para>
<section id="command-statistic-get">
<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
command may look like this:
<screen>
{
"command": "statistic-get",
"arguments": {
"name": "<userinput>pkt4-received</userinput>"
}
}
</screen>
</para>
<para>
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).
</para>
</section> <!-- end of command-statistic-get -->
<section id="command-statistic-reset">
<title>statistic-reset command</title>
<para>
<emphasis>statistic-reset</emphasis> 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 <command>name</command> that specifies the statistic name. An
example command may look like this:
<screen>
{
"command": "statistic-reset",
"arguments": {
"name": "<userinput>pkt4-received</userinput>"
}
}
</screen>
</para>
<para>
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.
</para>
</section> <!-- end of command-statistic-reset -->
<section id="command-statistic-remove">
<title>statistic-remove command</title>
<para>
<emphasis>statistic-remove</emphasis> command attempt to delete a single
statistic. It takes a single string parameter called
<command>name</command> that specifies the statistic name. An example
command may look like this:
<screen>
{
"command": "statistic-remove",
"arguments": {
"name": "<userinput>pkt4-received</userinput>"
}
}
</screen>
</para>
<para>
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.
</para>
</section> <!-- end of command-statistic-reset -->
<section id="command-statistic-get-all">
<title>statistic-get-all command</title>
<para>
<emphasis>statistic-get-all</emphasis> command retrieves a single
statistic. An example
command may look like this:
<screen>
{
"command": "statistic-get-all",
"arguments": { }
}
</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 total number of statistics is zero).
</para>
</section> <!-- end of command-statistic-get-all -->
<section id="command-statistic-reset-all">
<title>statistic-reset-all command</title>
<para>
<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:
<screen>
{
"command": "statistic-reset-all",
"arguments": { }
}
</screen>
</para>
<para>
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.
</para>
</section> <!-- end of command-statistic-reset-all -->
<section id="command-statistic-remove-all">
<title>statistic-remove-all command</title>
<para>
<emphasis>statistic-remove-all</emphasis> command attempt to delete all
statistics. An example command may look like this:
<screen>
{
"command": "statistic-remove-all",
"arguments": { }
}
</screen>
</para>
<para>
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.
</para>
</section> <!-- end of command-statistic-remove-all -->
</section>
</chapter>
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment