264 lines
9.5 KiB
Plaintext
264 lines
9.5 KiB
Plaintext
=head1 NAME
|
|
|
|
smokeping_extend - Notes on extending Smokeping
|
|
|
|
=head1 OVERVIEW
|
|
|
|
This document is intended to guide prospective authors in writing new
|
|
Smokeping probes. It mostly describes the interface between Smokeping
|
|
and its probe modules. If it seems too complicated to understand, look
|
|
at the existing modules for examples.
|
|
|
|
Comments and proposed changes or additions are welcome. Please send
|
|
them to the smokeping-users mailing list. Patches against the POD
|
|
source of this document are most appreciated.
|
|
|
|
=head1 CHOOSING A BASE CLASS
|
|
|
|
The first thing you should decide is which base class you should use for
|
|
your probe. For most (if not all) uses it's a choice between
|
|
L<Smokeping::probes::base|Smokeping::probes::base> and
|
|
L<Smokeping::probes::basefork|Smokeping::probes::basefork>. The former is
|
|
intended for probes that can measure their targets all in one go, while the
|
|
latter is for probing them one at a time, possibly in several concurrent
|
|
subprocesses.
|
|
|
|
At the moment, the only probes that use C<Smokeping::probes::base> are the FPing
|
|
derivatives. All the others use C<Smokeping::probes::basefork>, and chances are
|
|
you should too. This document will thus concentrate on the latter case.
|
|
|
|
=head1 SKELETON FILE
|
|
|
|
The L<Smokeping::probes::skel|Smokeping::probes::skel> module is a non-functional probe that is intended
|
|
to make a good basis for a new probe module. Copy the file,
|
|
C<lib/probes/skel.pm>, to a new name and just fill out the blanks :)
|
|
Note that the names of real probe modules must start with a capital letter.
|
|
|
|
=head1 PROBE DOCUMENTATION
|
|
|
|
The probe documentation is generated from the source code with the
|
|
L<smokeping|smokeping> arguments C<--man> or C<--makepod>. The embedded
|
|
POD documentation should point to this real documentation, so
|
|
that curious users of the C<perldoc> command see what's going on.
|
|
All the current probes do this.
|
|
|
|
You should provide the method C<pod_hash> that returns a reference to
|
|
a hash with keys corresponding to the section names you want in the
|
|
manpage. The supported section names are
|
|
C<name>, C<overview>, C<description>, C<authors>, C<notes>, C<bugs>, and
|
|
C<see_also>. If you don't need a particular section, just leave it out.
|
|
|
|
The special sections C<synopsis> and C<variables> are automatically
|
|
generated from the description of your variables. See below.
|
|
|
|
Note that if you use 'here documents' ('<<') that have POD markup inside,
|
|
you should escape the markup so that it doesn't show up in the embedded
|
|
POD documentation. Most probes do it like this:
|
|
|
|
my $e = "=";
|
|
my $doc = <<DOC;
|
|
${e}head1 SECTION TITLE
|
|
DOC
|
|
|
|
=head1 PROBE DESCRIPTION
|
|
|
|
The probe should offer the C<ProbeDesc> method that returns a short
|
|
description of what it does. This will be used in the graphs produced
|
|
by the web frontend.
|
|
|
|
=head1 VARIABLES
|
|
|
|
All Smokeping probes must define their variables by implementing a
|
|
C<probevars> method for probe-specific variables and a C<targetvars>
|
|
method for target-specific variables. If you don't know the difference
|
|
between these yet, see L<smokeping_examples>.
|
|
|
|
(The probes that are derived from C<Smokeping::probes::base> don't support
|
|
target-specific variables, so they only use the C<probevars> method.)
|
|
|
|
The base classes offer these methods too to provide the variables that
|
|
are common to all the probes (eg. the probe-specific C<step> variable
|
|
and the target-specific C<pings> variable. If you don't want to add
|
|
anything to the base class variables (perhaps because all your variables
|
|
are of a target-specific nature, so you don't need new probe-specific
|
|
variables at all), you can leave the corresponding method out and it
|
|
will be inherited from the base class.
|
|
|
|
When you do supply your own C<probevars> or C<targetvars> method, you should
|
|
combine your variables with those coming from the superclass. There is a
|
|
convenience method called C<_makevars> that does this, and the common idiom is
|
|
|
|
sub probevars {
|
|
my $class = shift;
|
|
return $class->_makevars($class->SUPER::probevars, {
|
|
# your variables go here
|
|
}
|
|
}
|
|
|
|
The variables are declared in a syntax that comes from the module used
|
|
for parsing the configuration file, C<Config::Grammar>. Each variable
|
|
should be a hash that uses the "special variable keys" documented in
|
|
L<Config::Grammar>. See C<Smokeping::probes::skel> and the other
|
|
probes for examples.
|
|
|
|
For reference, here are the keys the hash should have. Much of this
|
|
is taken straight from the C<Config::Grammar> manual.
|
|
|
|
=over
|
|
|
|
=item Keys you B<must> provide
|
|
|
|
=over
|
|
|
|
=item _doc
|
|
|
|
Description of the variable.
|
|
|
|
=item _example
|
|
|
|
An example value. This will be used in the SYNOPSIS section in the
|
|
probe manual.
|
|
|
|
=back
|
|
|
|
=item Optional keys
|
|
|
|
=over
|
|
|
|
=item _default
|
|
|
|
A default value that will be assigned to the variable if none is specified or inherited.
|
|
|
|
=item _re
|
|
|
|
Regular expression upon which the value will be checked.
|
|
|
|
=item _re_error
|
|
|
|
String containing the returned error in case the regular expression
|
|
doesn't match (if not specified, a generic 'syntax error' message will
|
|
be returned).
|
|
|
|
=item _sub
|
|
|
|
A function pointer. It is called for every value, with the value passed
|
|
as its first argument. If the function returns a defined value it is
|
|
assumed that the test was not successful and an error is generated with
|
|
the returned string as content.
|
|
|
|
=back
|
|
|
|
=back
|
|
|
|
The C<probevars> and C<targetvars> methods should return hash references
|
|
that contain the variable names as keys and the hashes described above
|
|
as values. In addition the C<Config::Grammar> special section key
|
|
C<_mandatory> is supported and should contain a reference to a list of
|
|
mandatory variables. The C<_makevars> method is aware of this special
|
|
key and merges the mandatory lists in its arguments. Note that no other
|
|
C<Config::Grammar> special section keys are supported.
|
|
|
|
=head1 INITIALIZATION
|
|
|
|
If you must do something at probe initialization time, like check that
|
|
the external program you're going to use behaves as you expect, you should
|
|
do it in the C<new> method. You should probably also take care that
|
|
you don't run the tests needlessly while in CGI mode. The usual way to
|
|
do this is to test for $ENV{SERVER_SOFTWARE}. See the C<Smokeping::probes::skel>
|
|
module for an example.
|
|
|
|
=head1 PINGING
|
|
|
|
All the real action happens in the C<pingone> method (or, for
|
|
C<Smokeping::probes::base>-derived probes, in the C<ping> method.) The arguments
|
|
for C<pingone> are C<$self>, the module instance (since this is a method)
|
|
and C<$target>, the target to be probed.
|
|
|
|
You can access the probe-specific variables here via the
|
|
C<$self-E<gt>{properties}> hash and the target-specific ones via the
|
|
C<$target-E<gt>{vars}> hash. You get the number of pings needed for
|
|
the target via the C<pings> method: C<my $count = $self-E<gt>pings($target)>.
|
|
|
|
You should return a sorted array of the latency times measured. If a ping
|
|
fails, don't put anything in the array.
|
|
|
|
That's it, you're done!
|
|
|
|
=head1 EXAMPLE CONFIGURATIONS
|
|
|
|
If you would like to provide a documented example configuration for your
|
|
probe (in addition to the automatically generated SYNOPSIS section in
|
|
the probe manual), you can do so by adding it to the L<Smokeping::Examples|Smokeping::Examples>
|
|
module. Look for the 'examples' subroutine and add your example there.
|
|
|
|
Future versions of Smokeping might provide a way to embed examples in
|
|
the probe modules too. The author's motivation for implementing this
|
|
would be greatly increased by even a single demand for it, so please
|
|
speak up if you think you'd use it.
|
|
|
|
=head1 TIMEOUT HANDLING
|
|
|
|
If you deal with timeouts (for example because your program offers a parameter
|
|
for specifying the timeout for the pings), you should know a few things.
|
|
|
|
First, there's timeout logic in C<Smokeping::probes::basefork> that kills the probe
|
|
when the timeout is reached. By default the timeout is (# of pings *
|
|
5 seconds) + 1 second. If you expect that your pings can take longer,
|
|
you should modify the default value of the probe-specific variable C<timeout>.
|
|
This would be done like this:
|
|
|
|
sub probevars {
|
|
my $class = shift;
|
|
my $h = $class->SUPER::probevars;
|
|
$h->{timeout}{_default} = 10; # override the superclass default
|
|
return $class->_makevars($h, {
|
|
# your variables go here
|
|
}
|
|
}
|
|
|
|
If you want to provide a target-specific C<timeout> setting, you should
|
|
delete the probe-specific variable and be sure to provide a default for
|
|
your target-specific one. See eg. C<Smokeping::probes::AnotherDNS> for an example of
|
|
how this is done.
|
|
|
|
Providing a target-specific C<timeout> will make the timeout in
|
|
C<Smokeping::probes::basefork> be (# of pings * the maximum timeout of all targets)
|
|
+ 1 second. The 1 second is added so that the own timeout logic of the
|
|
probe has time to kick in even in the worst case (ie. all pings are lost)
|
|
before C<Smokeping::probes::basefork> starts killing the processes.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2005 by Niko Tyni.
|
|
|
|
=head1 LICENSE
|
|
|
|
This program is free software; you can redistribute it
|
|
and/or modify it under the terms of the GNU General Public
|
|
License as published by the Free Software Foundation; either
|
|
version 2 of the License, or (at your option) any later
|
|
version.
|
|
|
|
This program is distributed in the hope that it will be
|
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
|
|
PURPOSE. See the GNU General Public License for more
|
|
details.
|
|
|
|
You should have received a copy of the GNU General Public
|
|
License along with this program; if not, write to the Free
|
|
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
|
|
02139, USA.
|
|
|
|
=head1 AUTHOR
|
|
|
|
Niko Tyni <ntyni@iki.fi>
|
|
|
|
=head1 BUGS
|
|
|
|
This document makes writing new probes look much harder than it really is.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
The other Smokeping documents, especially L<smokeping_config>.
|