<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	       [<!ENTITY mdash "&#8212;">]>
<!--
 - Copyright (C) 2010-2012  Internet Systems Consortium, Inc. ("ISC")
 -
 - Permission to use, copy, modify, and/or distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->

<refentry>

  <refentryinfo>
    <date>June 20, 2012</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>b10-stats</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND10</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>b10-stats</refname>
    <refpurpose>BIND 10 statistics module</refpurpose>
  </refnamediv>

  <docinfo>
    <copyright>
      <year>2010-2012</year>
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>b10-stats</command>
      <arg><option>-v</option></arg>
      <arg><option>--verbose</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>
      The <command>b10-stats</command> daemon collects statistics data
      from each BIND 10 module. Its statistics information may be
      reported via <command>bindctl</command> or
      <command>b10-stats-httpd</command>.  It is started by
      <command>bind10</command> and communicates by using the
      Command Channel by <command>b10-msgq</command> with other
      modules like <command>bind10</command>, <command>b10-auth</command>
      and so on. It waits for coming data from other modules, then
      other modules send data to stats module periodically. Other
      modules send stats data to stats module independently from
      implementation of stats module, so the frequency of sending
      data may not be constant. The stats module collects data and
      aggregates it. <command>b10-stats</command> invokes an internal
      command for <command>bind10</command> after its initial
      starting to make sure it collects statistics data from
      <command>bind10</command>.
    </para>
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>
    <para>The arguments are as follows:</para>
    <variablelist>
      <varlistentry>
        <term><option>-v</option>, <option>--verbose</option></term>
        <listitem>
	  <para>
          This enables maximum debug logging.
	  </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>CONFIGURATION AND COMMANDS</title>

    <para>
      The <command>b10-stats</command> command does not have any
      configurable settings.
    </para>

<!-- TODO: formating -->
    <para>
      The configuration commands are:
    </para>

    <para>
      <command>set</command> will set new statistics data specified in
      arguments. Statistics data to be set and the module name which owns
      statistics data are required in argument. Pid of the module in argument
      is optional.
    </para>

    <para>
      <command>show</command> will send the statistics data
      in JSON format.
      By default, it outputs all the statistics data it has collected.
      An optional item name may be specified to receive individual output.
    </para>

    <para>
      <command>showschema</command> will send the schema of the statistics data
      in JSON format. The output is equivalent to the statistics part
      of <filename>stats.spec</filename>.
    </para>

    <para>
      <command>shutdown</command> will shutdown the
      <command>b10-stats</command> process.
      This has an optional <varname>pid</varname> argument to
      select the process ID to stop.
      (Note that the BIND 10 boss process may restart this service
      if configured.)
    </para>

    <para>
      <command>status</command> simply indicates that the daemon is
      running.
    </para>

  </refsect1>

  <refsect1>
    <title>STATISTICS DATA</title>

    <para>
      The <command>b10-stats</command> daemon contains these
      <quote>Stats</quote> statistics:
    </para>

    <variablelist>


      <varlistentry>
        <term>boot_time</term>
        <listitem><simpara>The date and time when this daemon was
          started in ISO 8601 format.
          This is a constant which can't be reset except by restarting
          <command>b10-stats</command>.
        </simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>last_update_time</term>
        <listitem><simpara>The date and time (in ISO 8601 format)
          when this daemon last received data from another component.
        </simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>lname</term>
        <listitem><simpara>This is the name used for the
          <command>b10-msgq</command> command-control channel.
          (This is a constant which can't be reset except by restarting
          <command>b10-stats</command>.)
        </simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>report_time</term>
        <listitem><simpara>The latest report date and time in
          ISO 8601 format.</simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>start_time</term>
        <listitem><simpara>This is the date and time (in ISO 8601 format)
          when this daemon started collecting data.
        </simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>timestamp</term>
        <listitem><simpara>The current date and time represented in
          seconds since UNIX epoch (1970-01-01T00:00:00Z) with
          precision (delimited with a period) up to
          one hundred thousandth of second.</simpara></listitem>
      </varlistentry>

    </variablelist>

    <para>
      See other manual pages for explanations for their statistics
      that are kept track by <command>b10-stats</command>.
    </para>

  </refsect1>

  <refsect1>
    <title>FILES</title>
    <para><filename>/usr/local/share/bind10-devel/stats.spec</filename>
      <!--TODO: The filename should be computed from prefix-->
      &mdash; This is a spec file for <command>b10-stats</command>. It
      contains commands for <command>b10-stats</command>. They can be
      invoked
      via <refentrytitle>bindctl</refentrytitle><manvolnum>1</manvolnum>.
    </para>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>b10-stats-httpd</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>bindctl</refentrytitle><manvolnum>1</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citetitle>BIND 10 Guide</citetitle>.
    </para>
  </refsect1>

  <refsect1>
    <title>HISTORY</title>
    <para>
      The <command>b10-stats</command> daemon was initially designed
      and implemented by Naoki Kambe of JPRS in October 2010.
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->
