1SMOKEPING_EXTEND(7)                SmokePing               SMOKEPING_EXTEND(7)
2
3
4

NAME

6       smokeping_extend - Notes on extending Smokeping
7

OVERVIEW

9       This document is intended to guide prospective authors in writing new
10       Smokeping probes.  It mostly describes the interface between Smokeping
11       and its probe modules. If it seems too complicated to understand, look
12       at the existing modules for examples.
13
14       Comments and proposed changes or additions are welcome.  Please send
15       them to the smokeping-users mailing list. Patches against the POD
16       source of this document are most appreciated.
17

CHOOSING A BASE CLASS

19       The first thing you should decide is which base class you should use
20       for your probe.  For most (if not all) uses it's a choice between
21       Smokeping::probes::base and Smokeping::probes::basefork.  The former is
22       intended for probes that can measure their targets all in one go, while
23       the latter is for probing them one at a time, possibly in several
24       concurrent subprocesses.
25
26       At the moment, the only probes that use "Smokeping::probes::base" are
27       the FPing derivatives. All the others use
28       "Smokeping::probes::basefork", and chances are you should too. This
29       document will thus concentrate on the latter case.
30

SKELETON FILE

32       The Smokeping::probes::skel module is a non-functional probe that is
33       intended to make a good basis for a new probe module. Copy the file,
34       "lib/probes/skel.pm", to a new name and just fill out the blanks :)
35       Note that the names of real probe modules must start with a capital
36       letter.
37

PROBE DOCUMENTATION

39       The probe documentation is generated from the source code with the
40       smokeping arguments "--man" or "--makepod". The embedded POD
41       documentation should point to this real documentation, so that curious
42       users of the "perldoc" command see what's going on.  All the current
43       probes do this.
44
45       You should provide the method "pod_hash" that returns a reference to a
46       hash with keys corresponding to the section names you want in the
47       manpage. The supported section names are "name", "overview",
48       "description", "authors", "notes", "bugs", and "see_also". If you don't
49       need a particular section, just leave it out.
50
51       The special sections "synopsis" and "variables" are automatically
52       generated from the description of your variables. See below.
53
54       Note that if you use 'here documents' ('<<') that have POD markup
55       inside, you should escape the markup so that it doesn't show up in the
56       embedded POD documentation. Most probes do it like this:
57
58        my $e = "=";
59        my $doc = <<DOC;
60        ${e}head1 SECTION TITLE
61        DOC
62

PROBE DESCRIPTION

64       The probe should offer the "ProbeDesc" method that returns a short
65       description of what it does. This will be used in the graphs produced
66       by the web frontend.
67

VARIABLES

69       All Smokeping probes must define their variables by implementing a
70       "probevars" method for probe-specific variables and a "targetvars"
71       method for target-specific variables. If you don't know the difference
72       between these yet, see smokeping_examples.
73
74       (The probes that are derived from "Smokeping::probes::base" don't
75       support target-specific variables, so they only use the "probevars"
76       method.)
77
78       The base classes offer these methods too to provide the variables that
79       are common to all the probes (eg. the probe-specific "step" variable
80       and the target-specific "pings" variable. If you don't want to add
81       anything to the base class variables (perhaps because all your
82       variables are of a target-specific nature, so you don't need new probe-
83       specific variables at all), you can leave the corresponding method out
84       and it will be inherited from the base class.
85
86       When you do supply your own "probevars" or "targetvars" method, you
87       should combine your variables with those coming from the superclass.
88       There is a convenience method called "_makevars" that does this, and
89       the common idiom is
90
91        sub probevars {
92               my $class = shift;
93               return $class->_makevars($class->SUPER::probevars, {
94                       # your variables go here
95               }
96        }
97
98       The variables are declared in a syntax that comes from the module used
99       for parsing the configuration file, "Config::Grammar". Each variable
100       should be a hash that uses the "special variable keys" documented in
101       Config::Grammar. See "Smokeping::probes::skel" and the other probes for
102       examples.
103
104       For reference, here are the keys the hash should have. Much of this is
105       taken straight from the "Config::Grammar" manual.
106
107       Keys you must provide
108           _doc
109               Description of the variable.
110
111           _example
112               An example value. This will be used in the SYNOPSIS section in
113               the probe manual.
114
115       Optional keys
116           _default
117               A default value that will be assigned to the variable if none
118               is specified or inherited.
119
120           _re Regular expression upon which the value will be checked.
121
122           _re_error
123               String containing the returned error in case the regular
124               expression doesn't match (if not specified, a generic 'syntax
125               error' message will be returned).
126
127           _sub
128               A function pointer. It is called for every value, with the
129               value passed as its first argument. If the function returns a
130               defined value it is assumed that the test was not successful
131               and an error is generated with the returned string as content.
132
133       The "probevars" and "targetvars" methods should return hash references
134       that contain the variable names as keys and the hashes described above
135       as values. In addition the "Config::Grammar" special section key
136       "_mandatory" is supported and should contain a reference to a list of
137       mandatory variables. The "_makevars" method is aware of this special
138       key and merges the mandatory lists in its arguments. Note that no other
139       "Config::Grammar" special section keys are supported.
140

INITIALIZATION

142       If you must do something at probe initialization time, like check that
143       the external program you're going to use behaves as you expect, you
144       should do it in the "new" method. You should probably also take care
145       that you don't run the tests needlessly while in CGI mode. The usual
146       way to do this is to test for $ENV{SERVER_SOFTWARE}. See the
147       "Smokeping::probes::skel" module for an example.
148

PINGING

150       All the real action happens in the "pingone" method (or, for
151       "Smokeping::probes::base"-derived probes, in the "ping" method.) The
152       arguments for "pingone" are $self, the module instance (since this is a
153       method) and $target, the target to be probed.
154
155       You can access the probe-specific variables here via the
156       "$self->{properties}" hash and the target-specific ones via the
157       "$target->{vars}" hash. You get the number of pings needed for the
158       target via the "pings" method: "my $count = $self->pings($target)".
159
160       You should return a sorted array of the latency times measured. If a
161       ping fails, don't put anything in the array.
162
163       That's it, you're done!
164

EXAMPLE CONFIGURATIONS

166       If you would like to provide a documented example configuration for
167       your probe (in addition to the automatically generated SYNOPSIS section
168       in the probe manual), you can do so by adding it to the
169       Smokeping::Examples module.  Look for the 'examples' subroutine and add
170       your example there.
171
172       Future versions of Smokeping might provide a way to embed examples in
173       the probe modules too. The author's motivation for implementing this
174       would be greatly increased by even a single demand for it, so please
175       speak up if you think you'd use it.
176

TIMEOUT HANDLING

178       If you deal with timeouts (for example because your program offers a
179       parameter for specifying the timeout for the pings), you should know a
180       few things.
181
182       First, there's timeout logic in "Smokeping::probes::basefork" that
183       kills the probe when the timeout is reached. By default the timeout is
184       (# of pings * 5 seconds) + 1 second. If you expect that your pings can
185       take longer, you should modify the default value of the probe-specific
186       variable "timeout".  This would be done like this:
187
188        sub probevars {
189               my $class = shift;
190               my $h = $class->SUPER::probevars;
191               $h->{timeout}{_default} = 10; # override the superclass default
192               return $class->_makevars($h, {
193                       # your variables go here
194               }
195        }
196
197       If you want to provide a target-specific "timeout" setting, you should
198       delete the probe-specific variable and be sure to provide a default for
199       your target-specific one. See eg. "Smokeping::probes::AnotherDNS" for
200       an example of how this is done.
201
202       Providing a target-specific "timeout" will make the timeout in
203       "Smokeping::probes::basefork" be (# of pings * the maximum timeout of
204       all targets) + 1 second. The 1 second is added so that the own timeout
205       logic of the probe has time to kick in even in the worst case (ie. all
206       pings are lost) before "Smokeping::probes::basefork" starts killing the
207       processes.
208
210       Copyright 2005 by Niko Tyni.
211

LICENSE

213       This program is free software; you can redistribute it and/or modify it
214       under the terms of the GNU General Public License as published by the
215       Free Software Foundation; either version 2 of the License, or (at your
216       option) any later version.
217
218       This program is distributed in the hope that it will be useful, but
219       WITHOUT ANY WARRANTY; without even the implied warranty of
220       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
221       General Public License for more details.
222
223       You should have received a copy of the GNU General Public License along
224       with this program; if not, write to the Free Software Foundation, Inc.,
225       675 Mass Ave, Cambridge, MA 02139, USA.
226

AUTHOR

228       Niko Tyni <ntyni@iki.fi>
229

BUGS

231       This document makes writing new probes look much harder than it really
232       is.
233

SEE ALSO

235       The other Smokeping documents, especially smokeping_config.
236
237
238
2392.8.2                             2023-01-21               SMOKEPING_EXTEND(7)
Impressum