| Next: pre_redirect | Previous: data_sendmsg | [Table of Contents] | [Index] |
developer-guide - developer's guide to Spong
This is the developer guild to Spong. It documents the inner workings of the client and server programs. It also describes the plug-in mechanism of the spong-client and spong-network so that new check modules can be developed for these programs.
This section deals with the low level communication protocols that the clients use to talk with the spong-server. The Spong and Big Brothers protocols almost identical. They vary only in the data format.
The spong-server listens in on port 1998 for status updates from clients.
After a socket has been opened, the client program sends a message with the
following format:
command host service color time[:TTL] summary (\n)
detailed status message line 1 (\n)
detailed status message line 2 (\n)
...
detailed status message line n (\n)
Where:
df command or the top processes
by CPU utilization or the detailed responses of network checks.
The spong-server listens in on port 1984 for status Big Brother
client updates. After a socket has been opens the client sends a message
with the following format:
command host service color time summary (\n)
detailed status message line 1 (\n)
detailed status message line 2 (\n)
...
detailed status message line n (\n)
Where:
status which indicates a
service status update message.
spong-client, spong-network, spong-message and spong-server use various routines which are coded as modules. When the programs are initializing, they determine which modules are going to be required. The programs then go out and load each of the modules from the library directory. When the modules are loaded they register themselves with the plug-ins registry. The plug-in registry is the mechanism that the client programs use to keep track of the modules into order to run them.
spong-server has a hook that allows external programs access to the incoming status updates coming from Spong client programs. The hook takes the form of Server Data modules which are called after spong-server stores the status update in it's database.
spong-server passes all of the information of the update message in addition to the current event status duration to the Data Module. The modules should do any processing that they need to do in as short a time as possible. This is to minimize the resource overhead with lots of simultaneous status updates arrive at same time.
Debugging messages and error messages can be printed by using the &main::debug() and &main::error() functions respectively. If the module develops a fatal error, it should terminate using the die() or croak() functions depending on ones preference. Modules should just return upon a successful invocation.
NEW
There are two new types of Spong Server plugin modules: predata and postdata modules. The predata modules are called just after a message is received but before the normal Spong processing is done. And a post module is called after the Server's normal processing. i
Also in contrast to the old Spong Server data plugin modules all incoming messages a sent to the new predata and postdata modules, not just status messages. Predata modules can even flag a message to tell the Spong Server to drop the message and ignore it. This will allow you a great deal more access and control of the Server's incoming message processing.
Modules are called a predictable, controlable order. There are run in the order of the sorted registry hash keys. This allows you to create modules that have run dependencies.
And there is a new API to go along with the new modules. Now parameters are
passed in a Perl hash. This simplifies the module interface to the server. The
message type is determined by the cmd field. Message hash details are
in the the spong-server-mod-template manpage document.
See the spong-server-mod-template manpage for an example of how to code a spong-server Server Data Modules
Client modules define checks which are to be done on the host that the spong-client program is running on. The module's check function is called without any parameters. Client modules are expected to issue any systems command and parse the output in order to determine the service status.
Any threshold variables needed for warning and alert level trigger need to be
defined and placed into the SPONG/etc/spong.conf file. The threshold
variable need to be uniquely named and should be named according to the type of
check being done (i.e. $DISKWARN or $DFWARN for disk checks and $CPUWARN for
CPU checks, etc.).
Once the service status and messages have been determined the module
can call the &main::status() function in order to send the
information back to the spong-server. See the section on Status Function elsewhere in this document for more
information.
Network modules defined checks that to be done on hosts over the network to ensure that a network service is running. The modules are called with the name of the host the check is to be done to. The modules is also expected to put an alarm wrapper around the code that performs the check. This is to prevent excessive delays dues to lost communications. It is suggested that 10 seconds be used for the alarm setting.
The module should not call the &main::status() function directly. spong-network has a mechanism for rechecking services that are reported down on an initial check. If the recheck mechanism is engaged, "red" statuses will be downgraded to "yellow" until a failure count threshold is reached. The the services will be reported as "red".
After the status condition has been determined the check function should return three parameters:
These parameters are the same that will be passed to the &main::status()
command. See the section on Status Function elsewhere in this document for more information on these parameters.
The network modules have two support functions available,
&main::check_tcp() and &main::check_simple(), which can
simplify simple TCP port checks.
&main::check_tcp( host, port, data );
Where the arguments are:
The function &main::check_tcp() will make a connection to
the given PORT on the HOST and send a message (DATA). It then returns what
it gets back to the caller.
&main::check_simple( host, port, send, check, service)
Where the arguments are
The function &main::check_simple() is a generic TCP port checking
routine. This will go out connect to a given port (using &main::check_tcp()) and
check to make sure you get back expected results. The function returned
three parameters: STATUS, SUMMARY and MESSAGE as detailed above. The return
values of this function can returned as the necessary returned values of
the check module.
Message modules are function called to send a notification message to a contact on a specific service or service. The messaging functions are called with an the contacts identifier for the messaging service (i.e. the page PIN code of a paging provider). The messaging module is expected to take care of all of the data formating and communications logic to send a notification message to the contact.
The messaging functions has access to these global variable in order format a notification message:
There are two support functions that be used to format a message and send the
message via e-mail: &main::email_status() and
&main::email_mini_status(). Both functions format e-mail message to be
send to RECIPIENTS, but email_mini_status() sends out a shorter mail message
which is more suitable for SMS and smaller alpha pagers.
Both functions are called thusly:
&main::email_status( recipient, flags )
&main::email_mini_status( recipient, flags )
Where the arguments to the functions are:
The only flag current defined is 'shortsubject'. This prevents $color, $hostname, and $summary from being placed on the "subject:" line.
Creating the actual modules is very trivia to do. Create your module by following the appropriate template from below.
Then place your template module file into the appropriate directory below.
spong-client - LIBDIR/Spong/Client/plugins
spong-network - LIBDIR/Spong/Network/plugins
spong-message - LIBDIR/Spong/Message/plugins
spong-server - LIBDIR/Spong/plugins
Then test your modules by running the program with the --debug parameter to see if it is operating properly.
&main::status( SERVERADDR, HOST, SERVICE, COLOR, SUMMARY, MESSAGE )
The arguments to the &main::status() function are:
If you are reporting on multiple sets of like items (like file partitions or processes), report the names of those items that are abnormal, (i.e. "filesystems: / at 99%, /tmp at 100%").
ps command, or the output
of a df command for disk checking.
There are no limitations on the contexts of the field. You can include URL's that link to another monitor package or take you to an administration web page for the service in question.
the spong-server manpage, the spong-client manpage, the spong-network manpage, the spong-message manpage, the spong-server-mod-template manpage, the spong-client-mod-template manpage, the spong-network-mod-template manpage, the spong-message-mod-template manpage, the spong.conf manpage
Stephen L Johnson, <sjohnson@monsters.org>