From: Stephen L Johnson <sjohnson@monsters.org>
Date: Wed, 29 May 2002 03:32:34 +0000 (+0000)
Subject: added hash format for all Spong messages and created a new predata example
X-Git-Tag: spong-2_7_7~3
X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=18b0230c6eb69b6b2c7369e13a812d1ddf6321a6;p=spong.git

added hash format for all Spong messages and created a new predata example
module
---

diff --git a/pod/spong-server-mod-template.pod b/pod/spong-server-mod-template.pod
index f9d5066..2f71f0d 100755
--- a/pod/spong-server-mod-template.pod
+++ b/pod/spong-server-mod-template.pod
@@ -1,56 +1,248 @@
 =head1 NAME
 
-spong-server-mod-template - how to build a spong-server data module
+spong-server-mod-template - how to build a spong-server data modules
 
 =head1 DESCRIPTION
 
-This template will be a simple example that will write incoming 'cpu'
-status updates into a queueing directory. Each file will have the
-host's name plus the current time are it's file name. 
+The old data spong-server plugin modules are now deprecited in favor of predata
+and postdata modules. Spong Server data modules will continue to be supported
+for the future. But you are encouraged to convert any custom modules to the new
+format, and update any old data plugin to their new pre- or post-data
+equivalent.
 
-The file name of the module must begin with 'data_'. The registry key can
-be anything, but it should be consistent with the procedure's name. And the
-registry must be unique among the other loaded modules; otherwise, one
-module will overlay the other.
+The file name of the module must begin with 'predata_' or 'postdata_'.
+'predata_' is for a predata module. The module will be called immediately after
+an incoming message is received, but before normal processing. 'postdata_' is
+for a postdata module. The module is called after the normal processing is done
+for the message.
+
+Modules are called in the order of their registry key in alphabetical order.
+The registry key can be anything, but it should be consistent with the
+module's name.  And the registry must be unique among the other loaded
+modules; otherwise, one module will overlay the other.
 
 The line that has the assignment to C<$DATAFUNCS{'registry-name'}> is the
 key to the registry mechanism. It's what ties the registry name to the
 your data module.
 
-data_cpu_queue:
+=head1 Message Formats
+
+The fields of messages are passed to the module in the form of a Perl hash.
+This hash is the only parameter passed to the module when it is called. 
+
+=head2 Status Message
+
+This is the most common type of message received by the Spong Server. A status
+message reports the current status of Spong Client and Spong Network
+checks and tests.
+
+=over
+
+=item C<header>
+
+The field contains the first line of a status message. If consists the C<cmd>, 
+C<host>, C<color> (aka status), C<time>, and C<summary> fields.
+
+=item C<message>
+
+This is the detailed status message field.  It generally consists of multiple
+lines of text. This field can be quite large. Upwards of a few K is nor
+unusual.
+
+=item C<cmd>
+
+This is command field from the C<header>. It will a contain a string with the
+value of 'status'.
+
+=item C<host>
+
+This is hostname from the status message header field. It will contain the
+name of the reporting host. if will contain a strings that will typically be
+the fully qualified domain name of the host. It is the same of the hostname
+given in the L<spong.conf> configuation file.
+
+=item C<service>
+
+This is the service name from the message header field. It will contain a
+string. It it the name of the service or resource that was tested. The service
+names are the column names on the Web Status screens.
+
+=item C<color>
+
+This is the status color of the test being reported. It will contain a string consisting of one of these values: 'red', 'yellow', 'green', 'purple', 'clear'. The have a meaning of: red=critical, yellow=warning, green=normal, purple=old/stale data, clear=status unknown.
+
+=item C<time>
+
+This is the timestamp of the status as given by the rporting host. If will
+consist of system time in epoch format (i.e. as reported by time() ). Epoch
+date format is the number of seconds since a given epoch. Jan 1, 1970 12:00 AM
+for UNIX based systems.
+
+=item C<duration>
+
+The field contains the current duration that the service has been in it's
+current status (C<color>). The time is given in seconds.
+
+=item C<summary>
+
+This is summary fields from the status message. It is a short summary of the 
+current status of the services being reported.  It will be one line of test. Generally less then 40 characters (not guaranteed).
+
+=back
+
+=head2 Acknowledge Message
+
+Acknowledge messages are generate when an acknowledgement is created. This
+message is fairly rare. 
+
+=over
+
+=item C<header>
+
+The field contains the first line of a status message. If consists the C<cmd>, 
+C<host>, C<service>, C<start_time>, C<end_time>, and C<user> fields.
+
+=item C<message>
+
+This is an information/note field. It's typically used to give the reason for
+the acknoloedgement. It generally consists of multiple lines of text. This
+field can be quite large. 
+
+=item C<cmd>
+
+This is command field from the C<header>. It will a contain a string with the
+value of 'ack'.
+
+=item C<host>
+
+This is hostname the acknoledgement that is being created.  It will contain a
+strings that will typically be the fully qualified domain name of the host. It
+is the same of the hostname given in the L<spong.conf> configuation file.
+
+=item C<service>
+
+This field is the service(s) the acknowledgement is being created for. It will
+contain a string. It wll be a command seperated list of service names or the
+strings 'all' to represent all services.  The service names are the column
+names on the Web Status screens.
+
+=item C<start_time>
+
+This is the date/time of the start of the acknowledgement period.  It will
+consist of system time in epoch format (i.e. as reported by time() ). Epoch
+date format is the number of seconds since a given epoch. Jan 1, 1970 12:00 AM
+for UNIX based systems.
+
+=item C<end_time>
+
+This is the date/time of the end of the acknowledgement period.  It will
+consist of system time in epoch format (i.e. as reported by time() ). Epoch
+date format is the number of seconds since a given epoch. Jan 1, 1970 12:00 AM
+for UNIX based systems.
+
+=item C<user>
+
+This field gives and indication of the user who is creating the acknowledgment.
+This is just an informational field. It will consist of a string that contains
+an e-mail address (username@hostname).  This is not a hard and fast requirement. 
+=back
+
+=head2 Delete Acknowledge Message
+
+Delete Acknowledge messages are sent to delete an existing acknowledgement.
+This message is fairly rare. 
+
+=over
+
+=item C<header>
+
+The field contains the first line of a status message. If consists the C<cmd>, 
+C<host>,  C<service>, and C<end_time> fields.
+
+=item C<cmd>
+
+This is command field from the C<header>. It will a contain a string with the
+value of 'ack'.
+
+=item C<host>
+
+This is hostname of the acknoledgement that was created.  It will contain a
+strings that will typically be the fully qualified domain name of the host. It
+is the same of the hostname given in the L<spong.conf> configuation file.
+
+=item C<service>
+
+This field is the service(s) the acknowledgement is being created for. It will
+contain a string. It wll be a command seperated list of service names or the
+strings 'all' to represent all services.  The service names are the column
+names on the Web Status screens.
+
+=item C<end_time>
+
+This is the date/time of the end of the acknowledgement period.  It will
+consist of system time in epoch format (i.e. as reported by time() ). Epoch
+date format is the number of seconds since a given epoch. Jan 1, 1970 12:00 AM
+for UNIX based systems.
+
+=back
+
+=head2 Special Fields
+
+Predata modules add a special field/flag to the message hash before returning.
+The presence of this flag field will tell Spong Server to drop the message. The messge will be dropped and forgotten. Normal processing will not be done, and
+postdata modules will not be called.
+
+=over
+
+=item C<drop_msg>
+
+This field can be added to the passed messge field hash. If must be added with
+a none zero (0) value. See the example module below for it usage.
+
+=head1 Example Module
+
+This template will be a simple example that will redirect disk status updates
+to an alternate Spong Server for processing. We only want the Database Server
+hosts dbserv*.example.com. And we will tell the Spong Server to drop the
+message to let the alternate Spong Server to handle it.
+
+
+predata_redirect:
 
   # Register the routine with the plugin registry
-  $DATAFUNCS{'cpu_queue'} = \&data_cpu_queue;
+  $DATAFUNCS{'redirect'} = \&predata_redirect;
 
-  $CPU_QUEUE_DIR = "/var/spool/spong-queue";  # The spooling directory
+  use Spong::Status;  # We'll being this module to send the message
 
-  sub data_cpu_queue {
-     my( $host, $service, $color, $start, $time, $sum, $message ) = @_;
+  $ALTSERVER = 'spong-disk.example.com:19980';
 
-     if ( $service ne 'cpu' )  { return; }
+  sub predata_redirect {
+     my( $msg ) = @_;
 
-     my( $file ) = "$CPU_QUEUE_DIR/$host-" . time();
 
-     if (! open(FH,"> $file") ) {
-        &main::error("plugin::data_cpu_queue: Could not open file $file: $!");
-        return;
-     }
+     # Return is not status message for disk for dbserv* 
+     return if ( $msg->{'cmd'} ne 'status'  ||
+                 $msg->{'service'} ne 'disk' ||
+                 $msg->{'host'} !~ m/dbserv.*\.example\.com/ );
 
-     print FH "hostname: $host\n";
-     print FH "color: $color\n";
-     print FH "start-time: $start\n";
-     print FH "last-update: $time\n";
-     print FH "summary: $sum\n";
-     print FH "message:\n$message\n";
 
-     close FH;
+    # Send the message to the alternate Spong Disk server
+    Spong::Status($ALTSERV, 1998, $msg->{'header'} . "\n"
+                                  $msg->{'message'} );
+
+
+   # And tell the server to drop the message and don't process it
+   $msg->{'drop_msg'} = 1;
+
+   return;
 
-     &main::debug("plugin::data_cpu_queue: event written to file $file",5);
   }
 
   # I'm included perl code, I need this line.
   1;
 
+-----
+
 Please note the final line. It is always required for a module file.
 
 You should use the C<E<amp>main::error()> function to log any error encountered