NAME

OVERVIEW

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.

CHOOSING A BASE CLASS

At the moment, the only probes that use "Smokeping::probes::base" are the FPing derivatives. All the others use "Smokeping::probes::basefork", and chances are you should too. This document will thus concentrate on the latter case.

SKELETON FILE

PROBE DOCUMENTATION

You should provide the method "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 "name", "overview", "description", "authors", "notes", "bugs", and "see_also". If you don't need a particular section, just leave it out.

The special sections "synopsis" and "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

PROBE DESCRIPTION

VARIABLES

(The probes that are derived from "Smokeping::probes::base" don't support target-specific variables, so they only use the "probevars" method.)

The base classes offer these methods too to provide the variables that are common to all the probes (eg. the probe-specific "step" variable and the target-specific "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 "probevars" or "targetvars" method, you should combine your variables with those coming from the superclass. There is a convenience method called "_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, "Config::Grammar". Each variable should be a hash that uses the "special variable keys" documented in Config::Grammar. See "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 "Config::Grammar" manual.

Keys you must provide

Optional keys

The "probevars" and "targetvars" methods should return hash references that contain the variable names as keys and the hashes described above as values. In addition the "Config::Grammar" special section key "_mandatory" is supported and should contain a reference to a list of mandatory variables. The "_makevars" method is aware of this special key and merges the mandatory lists in its arguments. Note that no other "Config::Grammar" special section keys are supported.

INITIALIZATION

PINGING

You can access the probe-specific variables here via the "$self->{properties}" hash and the target-specific ones via the "$target->{vars}" hash. You get the number of pings needed for the target via the "pings" method: "my $count = $self->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!

EXAMPLE CONFIGURATIONS

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.

TIMEOUT HANDLING

First, there's timeout logic in "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 "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 "timeout" setting, you should delete the probe-specific variable and be sure to provide a default for your target-specific one. See eg. "Smokeping::probes::AnotherDNS" for an example of how this is done.

Providing a target-specific "timeout" will make the timeout in "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 "Smokeping::probes::basefork" starts killing the processes.

COPYRIGHT

LICENSE

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.

AUTHOR

BUGS

SEE ALSO