developer-guide
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:
- command
- The command being sent to the spong server indicating
a type of update message or a change in operating status of the client.
- host
- The fully qualified domain name of the host the message
is for.
- service
- The name of the service that the update message is
for.
- color
- The status color of the service (green - ok, yellow
- warning, red - alert).
- time
- The date/time of the update message in epoch time format
(i.e. the number of seconds since 01/01/70, 00:00 AM)
- TTL
- This optional field is the time to live, in seconds, for the status message.
Normally a will become stale (i.e. purple status) after 2 times $SPONGSLEEP
seconds which is the default. See the section on $SPONGSLEEP in the spong.conf manpage. This field will
override the default and keep the status message valid for a longer period of
time.
- summary
- The status summary message field. A short and to the point message that
summarizes the status being returned.
- detailed status message
- The remained lines of the message which will be the detailed information of the
status. Typically it can be the output of the
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:
- command
- The command being sent to the spong server indicating
a type of update message or a change in operating status of the client.
At present the only command defined is
status
which indicates a
service status update message.
- host
- The fully qualified domain name of the host the message
is for.
- service
- The name of the service that the update message is
for.
- color
- The status color of the service (green - ok, yellow
- warning, red - alert).
- time
- The date/time of the update message in standard date
format (i.e. Thu Jan 1 00:00:00 UTC 1970)
- summary
- The status summary message field.
- detailed status message
- The remained lines of the message
which will be the detailed information of the status. Typically it can
be the output of the df command or the top processes by CPU utilization
or the detailed responses of network checks.
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.
See the spong-server-mod-template manpage for an example of how to code a
spong-server Server Data Module.
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:
- STATUS
- The status color either "red", "yellow", or "green".
- SUMMARY
- A short line line summary of the status
- MESSAGE
- more detailed information (can be multi-lined)
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:
- HOST
- The name or ip address of the host to be checked.
- PORT
- The name, or port number, of service to connect with.
- DATA
- The data to be send to the host after the port is opened.
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
- HOST
- The name or ip address of the host to be checked.
- PORT
- The name of the port to connect with.
- SEND
- The message to sent to the host after the port is opened.
- CHECK
- A perl regular express to be used to validate the response return
by the host.
- SERVICE
- The name of the service being check. It is used in the summary
and detailed status messages.
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:
- $color
- The status color of the message
- $host
- The fully qualified domain name of the host
- $time
- The date and time of the message being sent. (format is
epoch time or time())
- $message
- A one line summary status line
- $duration
- The current duration of the current status in seconds.
(a zero duration indicates a change in status)
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:
- RECIPIENT
- one or more e-mail recipients which placed in the to: line
of the mail message.
- FLAGS
- flags to alter the formating of the message.
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:
- SERVERADDR
- Should be $SPONGSERVER.
- HOST
- The full hostname of the machine being reported.
- SERVICE
- The a short name that describes the service
that you are reporting on.
- COLOR
- The color of the status being reported, either "green", "yellow", or "red".
"green" denotes an OK status, there are no problems and everything is within
normal parameters. "yellow" denotes a warning status, a abnormal situation that
has which may be need to be looked at or a parameter has changed (up or down)
towards a critical level. "red" denotes an alert status, a critical situation
that has arisen and needs immediate attention or a parameter has changed (up
or down) to a critical level.
- SUMMARY
- A short one line summary of the status. This should be a short and concise
summary of the current situation of the service. The simplest form is to
say "Service is OK" or "Service is down". Another form is to display current
information (like system uptime, number of job and users) and additional
text for warning and alerts (i.e. "uptime - 123, jobs - 123, users - 123, cpu
load level is at 3.2").
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%").
- MESSAGE
- This is the place to put detailed information about the status of the service.
Typically this will be the output of the system commands or function calls. For example, it could be the 10 jobs by cpu usage in a
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
>
[Top]
Generated by Pod::HTML 0.41 on Wed Nov 29 21:02:20 2000