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

doc/guide/stats.xml

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