mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-31 14:05:33 +00:00
44c782060a
- improvements required (__VERSION__ macro omitted) - the patch tried to reverse some texts back to 1.1.0 (we're now at 1.3.0) - there were many conflicts... # Conflicts: # doc/guide/admin.xml # doc/guide/ctrl-channel.xml # doc/guide/ddns.xml # doc/guide/dhcp4-srv.xml # doc/guide/dhcp6-srv.xml # doc/guide/install.xml # doc/guide/intro.xml # doc/guide/kea-guide.xml # src/bin/admin/kea-admin.xml # src/bin/agent/kea-ctrl-agent.xml # src/bin/d2/kea-dhcp-ddns.xml # src/bin/dhcp4/kea-dhcp4.xml # src/bin/dhcp6/kea-dhcp6.xml # src/bin/keactrl/keactrl.xml # src/bin/lfc/kea-lfc.xml # src/bin/perfdhcp/perfdhcp.xml # src/bin/shell/kea-shell.xml # src/bin/sockcreator/kea-sockcreator.xml
269 lines
11 KiB
XML
269 lines
11 KiB
XML
<!--
|
|
- Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
|
|
-
|
|
- 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/.
|
|
-->
|
|
<!-- Converted by db4-upgrade version 1.1 -->
|
|
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="stats">
|
|
<title>Statistics</title>
|
|
|
|
<section>
|
|
<title>Statistics Overview</title>
|
|
|
|
<para>Both Kea DHCP servers support statistics gathering.
|
|
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
|
|
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
|
|
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
|
|
recording 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
|
|
recording statistics in textual form. It uses std::string C++ type.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
During normal operation, DHCPv4 and DHCPv6 servers gather statistics.
|
|
For a list of DHCPv4 and DHCPv6 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 or all statistics, reset statistics (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>
|
|
|
|
<section xml:id="stats-lifecycle">
|
|
<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
|
|
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
|
|
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
|
|
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 next records that statistic.
|
|
The <command>statistic-remove</command> and
|
|
<command>statistic-remove-all</command> commands are intended to remove
|
|
statistics that are 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, the system administrator may want to remove the
|
|
pkt4-decline-received statistic, so it won't be reported anymore. If a
|
|
duplicate address is detected ever again, the server will add this
|
|
statistic back.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml: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. 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
|
|
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
|
|
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
|
|
sending commands to Kea, see <xref linkend="ctrl-channel"/>.
|
|
</para></note>
|
|
|
|
<section xml: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 the requested statistic, with result
|
|
set to 0 indicating success and the specified statistic as the value of
|
|
"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).
|
|
</para>
|
|
</section> <!-- end of command-statistic-get -->
|
|
|
|
<section xml:id="command-statistic-reset">
|
|
<title>statistic-reset command</title>
|
|
|
|
<para>
|
|
<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
|
|
example command may look like this:
|
|
<screen>
|
|
{
|
|
"command": "statistic-reset",
|
|
"arguments": {
|
|
"name": "<userinput>pkt4-received</userinput>"
|
|
}
|
|
}
|
|
</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.
|
|
</para>
|
|
</section> <!-- end of command-statistic-reset -->
|
|
|
|
<section xml:id="command-statistic-remove">
|
|
<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
|
|
command may look like this:
|
|
<screen>
|
|
{
|
|
"command": "statistic-remove",
|
|
"arguments": {
|
|
"name": "<userinput>pkt4-received</userinput>"
|
|
}
|
|
}
|
|
</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.
|
|
</para>
|
|
</section> <!-- end of command-statistic-reset -->
|
|
|
|
<section xml:id="command-statistic-get-all">
|
|
<title>statistic-get-all command</title>
|
|
|
|
<para>
|
|
<emphasis>statistic-get-all</emphasis> command retrieves all statistics
|
|
recorded. 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 xml: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 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.
|
|
</para>
|
|
</section> <!-- end of command-statistic-reset-all -->
|
|
|
|
<section xml:id="command-statistic-remove-all">
|
|
<title>statistic-remove-all command</title>
|
|
|
|
<para>
|
|
<emphasis>statistic-remove-all</emphasis> command attempts to delete all
|
|
statistics. An example command may look like this:
|
|
<screen>
|
|
{
|
|
"command": "statistic-remove-all",
|
|
"arguments": { }
|
|
}
|
|
</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)
|
|
and the text field will contain the error description.
|
|
</para>
|
|
</section> <!-- end of command-statistic-remove-all -->
|
|
|
|
</section>
|
|
|
|
</chapter>
|