kea/doc/guide/stats.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash  "&#x2014;" >
]>

<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>
      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>

  <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>