From b9ddd9310ea896a5e644f784013a386d9e7212a9 Mon Sep 17 00:00:00 2001 From: Tobi Oetiker Date: Fri, 11 Feb 2005 20:48:36 +0000 Subject: niko has revamped smokeping to parse configuration much more strictly. It is all documented in software/doc/smokeping_upgrade.pod --- doc/smokeping_extend.pod | 241 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 doc/smokeping_extend.pod (limited to 'doc/smokeping_extend.pod') diff --git a/doc/smokeping_extend.pod b/doc/smokeping_extend.pod new file mode 100644 index 0000000..6ee0133 --- /dev/null +++ b/doc/smokeping_extend.pod @@ -0,0 +1,241 @@ +=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 this file +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 +C and C. 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 are the FPing +derivatives. All the others use C, and chances are +you should too. This document will thus concentrate on the latter case. + +=head1 SKELETON FILE + +The C module is a non-functional probe that is intended +to make a good basis for a new probe module. Copy the file, +C, to a new name and just fill out the blanks :) +Note that real probe modules must have at least one capital letter +in their name. + +=head1 PROBE DOCUMENTATION + +The probe documentation is generated from the source code with the +C arguments C<--man> or C<--makepod>. The embedded +POD documentation should point to this real documentation, so +that curious users of the C command see what's going on. +All the current probes do this. + +You should provide the method C 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, C, C, C, C, C, and +C. If you don't need a particular section, just leave it out. + +The special sections C and C are automatically +generated from the description of your variables. See below. + +=head1 PROBE DESCRIPTION + +The probe should offer the C 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 method for probe-specific variables and a C +method for target-specific variables. If you don't know the difference +between these yet, see the L document. + +(The probes that are derived from C don't support +target-specific variables, so they only use the C method.) + +The base classes offer these methods too to provide the variables that +are common to all the probes (eg. the probe-specific C variable +and the target-specific C 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 or C 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. Each variable +should be a hash that uses the "special variable keys" documented in +the C manual. See the C 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 manual. + +=over + +=item Keys you B provide + +=over + +=item _doc + +Description of the variable. + +=item _example + +An example value. This will be used in the SYNOPSYS 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 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 and C methods should return hash references +that contain the variable names as keys and the hashes described above +as values. In addition the C special section key +C<_mandatory> is supported and should contain a reference to a list of +mandatory variables. The C<_makevars> method is available of this special +key and merges the mandatory lists in its arguments. Note that no other +C 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 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 +module for an example. + +=head1 PINGING + +All the real action happens in the C method (or, for +C-derived probes, in the C method.) The arguments +for C 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{properties}> hash and the target-specific ones via the +C<$target-E{vars}> hash. You get the number of pings needed for +the target via the C method: Cpings($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 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 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. +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 setting, you should +delete the probe-specific variable and be sure to provide a default for +your target-specific one. See eg. C for an example of +how this is done. + +Providing a target-specific C will make the timeout in +C 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 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 + +=head1 BUGS + +This document makes writing new probes look much harder than it really is. + +=head1 SEE ALSO + +The other Smokeping documents, especially smokeping_config. -- cgit v1.2.3-24-g4f1b