summaryrefslogtreecommitdiffstats
path: root/doc/reports.xml
diff options
context:
space:
mode:
authorJoey Hagedorn <hagedorn@mcs.anl.gov>2006-04-04 20:35:56 +0000
committerJoey Hagedorn <hagedorn@mcs.anl.gov>2006-04-04 20:35:56 +0000
commit40b7d470cb03ac18115d45a089d56d0552b8e145 (patch)
treed3cbcbb28c407eff2b0885471e5626ca92674916 /doc/reports.xml
parentdc4a28c0bb59edc9385d6860ed1b7defeeacde42 (diff)
downloadbcfg2-40b7d470cb03ac18115d45a089d56d0552b8e145.tar.gz
bcfg2-40b7d470cb03ac18115d45a089d56d0552b8e145.tar.bz2
bcfg2-40b7d470cb03ac18115d45a089d56d0552b8e145.zip
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
Diffstat (limited to 'doc/reports.xml')
-rw-r--r--doc/reports.xml176
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>