Updated documentation for Reports.

Added Subversion Revision Info to nodes-digest and overview-stats HTML reports

added new report type with table of machines called overview-matrix-www


git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@1824 ce84e21b-d406-0410-9b95-82705330c041

1 files changed, 87 insertions, 89 deletions

diff --git a/doc/reports.xml b/doc/reports.xml
index ce49597c9..23493658e 100644
--- a/doc/reports.xml
+++ b/doc/reports.xml
@@ -4,12 +4,11 @@
   <para>
     Reports play an important role in effectively managing systems
     with BCFG. There are two primary functions they fulfill; providing
-    otherwise unobtainable information, and presenting additional
-    helpful information to allow for easier admistration. Reports
-    can contain information including system statistics, discrepancies
-    between specified and actual configuration, invalid configuration,
-    and auditing information among other things.
-  </para>
+    otherwise unobtainable information, and presenting common
+    information in a compact, effective format that allows for easier
+    admistration. Reports can contain system statistics, discrepancies
+    between specified and actual configuration, invalid configuration
+    notices, and auditing information, among other things.  </para>
 
   <para>
     The flexible XML configuration file allows reports to be configured
@@ -21,20 +20,20 @@
   </para>
 
   <section>
-    <title>How it all works</title>
+    <title>How it works</title>
 
     <para>
-      The BCFG2 Reporting System consists of a number of elements. The
-      core is the <command>StatReports</command>
-      Executable. <command>StatReports</command> reads a default
+      The BCFG2 Reporting System consists of a number of elements
+      including the <command>StatReports</command> Executable, a
+      configuration file, and XSLT transform
+      files. <command>StatReports</command> reads a default
       configuration file (or a config file specified on the command
-      line) then prepares and delivers the reports specified in the
-      configuration file. It is expected that this executable will be
-      run by the adminstrator periodically via <command>cron</command>
-      or similar facilty. The executable can also be run manually on
-      demand for a special sort of report that needs to be generated
-      immediately.
-    </para>
+      line) then prepares and delivers the reports according to the
+      format defined in the transform files. It is expected that this
+      executable will be run by the adminstrator periodically via
+      <command>cron</command> or similar facility. The executable can
+      also be run manually on demand for a special sort of report that
+      needs to be generated immediately.  </para>
     
     <para>
       <command>StatReports</command> gets the data it reports from a
@@ -42,29 +41,22 @@
       contains information about if a host is currently pingable or
       not. <command>GenerateHostInfo</command> will be run
       automatically by <command>StatReports</command> if the
-      <filename>Metadata/clients.xml</filename> file is older than
-      23.5 hours. We chose this interval due to our normal use of
-      reports; clients run bcfg2, in general, once a day after which
-      reports are delivered to administrators.  It is possible to
-      execute <command>GenerateHostInfo</command> to update the
-      <filename>Metadata/clients.xml</filename> file at any interval
-      via cron, but it does take some time to complete, so be sure to
-      give it a few minutes. This will only likely be of use if your
-      BCFG clients are set to update more often than nightly and you
-      would like reports after each run.
+      <filename>Metadata/clients.xml</filename> file is out of date
+      with pingability information.
     </para>
     
     <para>
-      The next place <command>StatReports</command> gets data from is the
-      <filename>statistics.xml</filename>
-      file. This file is maintained by bcfgd, and is updated whenever a
-      client updates, therefore is always up to date, and no
-      maintainance is required on this file.
+      The next place <command>StatReports</command> gets data from is
+      the <filename>statistics.xml</filename> file. This file is
+      maintained by bcfgd, and is updated whenever a client updates,
+      therefore is always up to date and no maintainance is required
+      on this file. Most of the information in the predefined reports
+      come from this file.
     </para>
     
     <para>
-      Finally <command>StatReports</command> is able to get information
-      out of the <filename>Metadata/groups.xml</filename> file as well.
+      Finally <command>StatReports</command> is able to pull information
+      from the <filename>Metadata/groups.xml</filename> file as well.
       This allows reports to describe the configured profile for each client.
     </para>	
   </section>
@@ -73,16 +65,16 @@
     <title>Report Types</title>
     
     <para>
-      There are a number of report types, and a number of delivery
-      styles. It is expected that reports be laid out around a group
-      of machines. For any group of machines it can be defined that
-      there be any number of reports generated, with different
-      options. For each of those reports, each can be delivered by
-      Mail, WWW, or via RSS (or any combination of the three.) In the
-      future, additional report types will be added, and if necessary,
-      additional types of deliveries will be created. Tables
-      describing report types and report delivery mechanisms follow.
-    </para>
+      There are a number of report types and delivery styles to
+      present and transmit the reported data. The reporting structure
+      lends itself best to structuring reports around groups of
+      machines. For any group of machines any number of reports are
+      generated.  Each report may be delivered via Mail, WWW, or RSS
+      (or any combination of the three.) In the future additional
+      report types will be added, and if necessary, additional types
+      of deliveries will be created. It is easy to create your own
+      custom report using XSLT. Tables describing report types and
+      report delivery mechanisms follow:  </para>
 
     <table>
       <title>Bcfg2 Report Types</title>
@@ -96,13 +88,13 @@
 	  <row><entry>Overview-Stats</entry>
 	    <entry>
 	      <para>
-		This report provides information about a large number of
-		machines and their states. It is often found to be useful
-		when the group of machines it is connected with is simply
-		All Nodes, which gives an overall outlook on your
-		network's health. It makes sense to get this report via
-		any mechanism
-	      </para>
+		This report provides information about a large number
+		of machines and their states. It is often found to be
+		useful when the constituent machines are simply
+		specified as All Nodes, which gives an overall outlook
+		on your network's health. It makes sense to get this
+		report via any mechanism.
+              </para>
 	    </entry></row>
 	  <row><entry>Nodes-Digest</entry>
 	    <entry>
@@ -110,7 +102,7 @@
 		This report includes details about each node,
 		specifically what packages, files, etc are broken, and
 		other node specific info. It makes sense to recieve
-		this via any mechanism
+		this via any mechanism.
 	      </para>
 	    </entry></row>
 	  <row><entry>Nodes-Individual</entry>
@@ -118,11 +110,12 @@
 	      <para>
 		This report includes details about each node, but
 		information is separated in to separate sections (such
-		as separate e-mails or RSS articles) before
-		sending. This works well with e-mail filters and error
-		detection. Currently WWW is not a supported delivery
-		mechanism for this type of report, because it is not
-		completely clear how such a report could be used.
+		as separate e-mails or RSS articles) for delivery.
+		This works well with e-mail (using filters on the
+		client side) and for error detection (getting e-mail
+		when there is a problem. Currently WWW is not a supported
+		delivery mechanism for this type of report, because it is
+		not completely clear how such a report could be used.
 	      </para>
 	    </entry></row>
 	</tbody>
@@ -138,10 +131,10 @@
 	  <row><entry>Name</entry><entry>Description</entry></row>
 	</thead>
 	<tbody>
-	  <row><entry>www</entry><entry>XHTML file</entry></row>
-	  <row><entry>rss</entry><entry>An RSS file <comment>(links do
+	  <row><entry>www</entry><entry>an XHTML file</entry></row>
+	  <row><entry>rss</entry><entry>an RSS file <comment>(links do
 	  not point at real web links, since they may not exist)</comment></entry></row>
-	  <row><entry>mail</entry><entry>A plaintext email
+	  <row><entry>mail</entry><entry>A plaintext e-mail
 	  message</entry></row>
 	</tbody>
       </tgroup>
@@ -152,13 +145,14 @@
   <section>
     <title>Configuration</title>
     
-    <para>The <filename>report-configuration.xml</filename> file is the
-      standard file that is used
-      whenever the <command>StatReports</command> executable is run without any
-      command line arguments. Alternate configuration files, formatted 
-      identically, can be used instead with the -c flag. This can be useful
-      for running different types of reports at different intervals. For
+    <para>The <filename>report-configuration.xml</filename> file is
+      the standard file that the <command>StatReports</command>
+      executable uses when it is run without any command line
+      arguments. Alternate configuration files, formatted identically,
+      can be used by specifing -c flag. This can be useful for
+      running different types of reports at different intervals. For
       example:</para>
+
     <programlisting>
       Run this hourly: StatReports -c WebAndRssReport-config.xml
       Run this daily: StatReports -c emailReports-config.xml
@@ -170,23 +164,23 @@
       of
       <![CDATA[<Report/>]]> tags can be inserted. Each report is structured 
       around a group of machines. <![CDATA[<Machine/>]]> tags may individually
-      reference a machine by hostname (not FQDN), or also by a Python Regular
-      Expression. More information can be found about such Regexes at:
-      <ulink url="http://docs.python.org/lib/re-syntax.html"/>.</para>
-
-    <para>Any number of <![CDATA[<Delivery/>]]> elements can be made for a 
-      given
-      report. A delivery consists of a mechanism and a type.
-      The mechanism would be 
-      something like Mail or Web, and they type would reference the content
-      of the report. Some are tailored to overall machine health, while
+      reference a machine by hostname, or by a Python Regular
+      Expression describing a group of hostnames. ".*" is especially helpful
+      to describe all hosts. More information can be found about such Regexes
+      at: <ulink url="http://docs.python.org/lib/re-syntax.html"/>.</para>
+
+    <para>Any number of <![CDATA[<Delivery/>]]> elements can be
+      defined for a given report. A delivery consists of a mechanism
+      and type.  The mechanism would be something like Mail or Web,
+      and the type would describe the intended content of the
+      report. Some are tailored to overall machine health, while
       others could be best fit for auditing purposes</para>
 
-    <para>Finally, each <![CDATA[<Delivery/>]]> contains one or more
-      <![CDATA[<Destination/>]]> tags. In the
-      case of an RSS or WWW report, the destination should be a complete path
-      to the output file. In e-mail based reports the destination should be
-      a complete e-mail address.</para>
+    <para>Finally, each <![CDATA[<Delivery/>]]> element contains one
+      or more <![CDATA[<Destination/>]]> elements. In the case of an
+      RSS or WWW report, the destination should be a complete path to
+      the output file including the file's name. In e-mail based
+      reports the destination should be a valid e-mail address.</para>
 
   </section>
 
@@ -194,11 +188,10 @@
     <title>Reporting Quick Start</title>
 
     <para>
-      This configuration will generate two separate reports and
-      deliver them a number of different ways. For more information on
-      exactly what each section does, please refer to the
-      Configuration section above.
-    </para>
+      The following configuration will generate two separate reports
+      and deliver them in a number of different ways. For more
+      information on exactly what each section does, please refer to
+      the Configuration section above.  </para>
 
   <example>
   <title>etc/report-configuration.xml</title>
@@ -230,9 +223,14 @@
 
   <para>
       Once configured correctly, just wait for the e-mail or view the
-      outputed html files with a web browser. You can run
-      <command>StatReports</command> by hand if you would like in
-      order to try it out immediately.
+      outputed html files with a web browser.
+      <command>StatReports</command> to recieve your reports
+      immediately, or configure cron to run it perodically. E-mail
+      reports will deliver the appropriate content directly to your
+      mail client, and the html files should be viewable with any web
+      browser. It is suggested those files be accessable via a
+      webserver for convenience to other interested parties.
+
     </para>
     
     <mediaobject>