=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
projects / spong.git / commitdiff