commit f30d061039fc9b5f0d2c2fc786ae725ce3abb694
Author: Spyros Trigazis <strigazi@gmail.com>
Date:   Mon Sep 30 08:54:31 2013 +0300

    Update hail, hbal and htools man-pages
    
    Update hail, hbal and htools man-pages to include the use of data
    provided by MonD.
    
    Signed-off-by: Spyros Trigazis <strigazi@gmail.com>
    Signed-off-by: Michele Tartara <mtartara@google.com>
    Reviewed-by: Michele Tartara <mtartara@google.com>

diff --git a/man/hail.rst b/man/hail.rst
index 72733a2..c7fe773 100644
--- a/man/hail.rst
+++ b/man/hail.rst
@@ -27,6 +27,10 @@ on stderr and the exit code is changed to show failure.
 If the input file name is ``-`` (a single minus sign), then the request
 data will be read from *stdin*.
 
+Apart from input data, hail collects data over the network from all
+MonDs with the --mond option. Currently it uses only data produced by
+the CPUload collector.
+
 ALGORITHM
 ~~~~~~~~~
 
@@ -75,6 +79,25 @@ The options that can be passed to the program are as follows:
   in the JSON request itself. This is mostly used for debugging. The
   format of the file is described in the man page **htools**\(1).
 
+\--mond
+  If given the program will query all MonDs to fetch data from the
+  supported data collectors over the network.
+
+\--mond-data *datafile*
+  The name of the file holding the data provided by MonD, to override
+  quering MonDs over the network. This is mostly used for debugging. The
+  file must be in JSON format and present an array of JSON objects ,
+  one for every node, with two members. The first member named ``node``
+  is the name of the node and the second member named ``reports`` is an
+  array of report objects. The report objects must be in the same format
+  as produced by the monitoring agent.
+
+\--ignore-dynu
+  If given, all dynamic utilisation information will be ignored by
+  assuming it to be 0. This option will take precedence over any data
+  passed by the MonDs with the ``--mond`` and the ``--mond-data``
+  option.
+
 \--simulate *description*
   Backend specification: similar to the **-t** option, this allows
   overriding the cluster data with a simulated cluster. For details
diff --git a/man/hbal.rst b/man/hbal.rst
index 218ff56..4ef2371 100644
--- a/man/hbal.rst
+++ b/man/hbal.rst
@@ -58,6 +58,10 @@ reasonably fast. It is not, however, designed to be a perfect algorithm:
 it is possible to make it go into a corner from which it can find no
 improvement, because it looks only one "step" ahead.
 
+The program accesses the cluster state via Rapi or Luxi. It also
+requests data over the network from all MonDs with the --mond option.
+Currently it uses only data produced by CPUload collector.
+
 By default, the program will show the solution incrementally as it is
 computed, in a somewhat cryptic format; for getting the actual Ganeti
 command list, use the **-C** option.
@@ -121,6 +125,7 @@ following components:
   primary instances of the node)
 - standard deviation of the dynamic load on the nodes, for cpus,
   memory, disk and network
+- standard deviation of the CPU load provided by MonD
 
 The free memory and free disk values help ensure that all nodes are
 somewhat balanced in their resource usage. The reserved memory helps
@@ -159,6 +164,13 @@ different), and that they are normalised to between zero and one. Note
 that it's recommended to not have zero as the load value for any
 instance metric since then secondary instances are not well balanced.
 
+The CPUload from MonD's data collector will be used only if all MonDs
+are running, otherwise it won't affect the cluster score. Since we can't
+find the CPU load of each instance, we can assume that the CPU load of
+an instance is proportional to the number of its vcpus. With this
+heuristic, instances from nodes with high CPU load will tend to move to
+nodes with less CPU load.
+
 On a perfectly balanced cluster (all nodes the same size, all
 instances the same size and spread across the nodes equally), the
 values for all metrics would be zero. This doesn't happen too often in
@@ -320,7 +332,8 @@ The options that can be passed to the program are as follows:
 \--ignore-dynu
   If given, all dynamic utilisation information will be ignored by
   assuming it to be 0. This option will take precedence over any data
-  passed by the ``-U`` option.
+  passed by the ``-U`` option or by the MonDs with the ``--mond`` and
+  the ``--mond-data`` option.
 
 -S *filename*, \--save-cluster=*filename*
   If given, the state of the cluster before the balancing is saved to
@@ -336,6 +349,19 @@ The options that can be passed to the program are as follows:
   other backends must be selected. The option is described in the man
   page **htools**\(1).
 
+\--mond
+  If given the program will query all MonDs to fetch data from the
+  supported data collectors over the network.
+
+\--mond-data *datafile*
+  The name of the file holding the data provided by MonD, to override
+  quering MonDs over the network. This is mostly used for debugging. The
+  file must be in JSON format and present an array of JSON objects ,
+  one for every node, with two members. The first member named ``node``
+  is the name of the node and the second member named ``reports`` is an
+  array of report objects. The report objects must be in the same format
+  as produced by the monitoring agent.
+
 -m *cluster*
   Backend specification: collect data directly from the *cluster* given
   as an argument via RAPI. The option is described in the man page
diff --git a/man/htools.rst b/man/htools.rst
index ecd5ece..37591aa 100644
--- a/man/htools.rst
+++ b/man/htools.rst
@@ -219,6 +219,25 @@ support all options. Some common options are:
   - vcpu ratio
   - spindle ratio
 
+\--mond
+  If given the program will query all MonDs to fetch data from the
+  supported data collectors over the network.
+
+\--mond-data *datafile*
+  The name of the file holding the data provided by MonD, to override
+  quering MonDs over the network. This is mostly used for debugging. The
+  file must be in JSON format and present an array of JSON objects ,
+  one for every node, with two members. The first member named ``node``
+  is the name of the node and the second member named ``reports`` is an
+  array of report objects. The report objects must be in the same format
+  as produced by the monitoring agent.
+
+\--ignore-dynu
+  If given, all dynamic utilisation information will be ignored by
+  assuming it to be 0. This option will take precedence over any data
+  passed by the ``-U`` option (available with hbal) or by the MonDs with
+  the ``--mond`` and the ``--mond-data`` option.
+
 -m *cluster*
   Backend specification: collect data directly from the *cluster* given
   as an argument via RAPI. If the argument doesn't contain a colon (:),
