<!ENTITY mdash "—" >
]>
- <!-- 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>
projects / thirdparty / kea.git / commitdiff
