path: root/doc/guide/stats.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>