From 40b7d470cb03ac18115d45a089d56d0552b8e145 Mon Sep 17 00:00:00 2001 From: Joey Hagedorn Date: Tue, 4 Apr 2006 20:35:56 +0000 Subject: 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 --- doc/reports.xml | 176 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 87 insertions(+), 89 deletions(-) (limited to 'doc') 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 @@ 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. - + 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. The flexible XML configuration file allows reports to be configured @@ -21,20 +20,20 @@
- How it all works + How it works - The BCFG2 Reporting System consists of a number of elements. The - core is the StatReports - Executable. StatReports reads a default + The BCFG2 Reporting System consists of a number of elements + including the StatReports Executable, a + configuration file, and XSLT transform + files. StatReports 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 cron - or similar facilty. The executable can also be run manually on - demand for a special sort of report that needs to be generated - immediately. - + 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 + cron or similar facility. The executable can + also be run manually on demand for a special sort of report that + needs to be generated immediately. StatReports gets the data it reports from a @@ -42,29 +41,22 @@ contains information about if a host is currently pingable or not. GenerateHostInfo will be run automatically by StatReports if the - Metadata/clients.xml 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 GenerateHostInfo to update the - Metadata/clients.xml 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. + Metadata/clients.xml file is out of date + with pingability information. - The next place StatReports gets data from is the - statistics.xml - 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 StatReports gets data from is + the statistics.xml 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. - Finally StatReports is able to get information - out of the Metadata/groups.xml file as well. + Finally StatReports is able to pull information + from the Metadata/groups.xml file as well. This allows reports to describe the configured profile for each client.
@@ -73,16 +65,16 @@ Report Types - 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. - + 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: Bcfg2 Report Types @@ -96,13 +88,13 @@ Overview-Stats - 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 - + 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. + Nodes-Digest @@ -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. Nodes-Individual @@ -118,11 +110,12 @@ 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. @@ -138,10 +131,10 @@ NameDescription - wwwXHTML file - rssAn RSS file (links do + wwwan XHTML file + rssan RSS file (links do not point at real web links, since they may not exist) - mailA plaintext email + mailA plaintext e-mail message @@ -152,13 +145,14 @@
Configuration - The report-configuration.xml file is the - standard file that is used - whenever the StatReports 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 + The report-configuration.xml file is + the standard file that the StatReports + 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: + Run this hourly: StatReports -c WebAndRssReport-config.xml Run this daily: StatReports -c emailReports-config.xml @@ -170,23 +164,23 @@ of ]]> tags can be inserted. Each report is structured around a group of machines. ]]> 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: - . - - Any number of ]]> 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: . + + Any number of ]]> 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 - Finally, each ]]> contains one or more - ]]> 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. + Finally, each ]]> element contains one + or more ]]> 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.
@@ -194,11 +188,10 @@ Reporting Quick Start - 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. - + 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. etc/report-configuration.xml @@ -230,9 +223,14 @@ Once configured correctly, just wait for the e-mail or view the - outputed html files with a web browser. You can run - StatReports by hand if you would like in - order to try it out immediately. + outputed html files with a web browser. + StatReports 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. + -- cgit v1.2.3-1-g7c22