1SMOKEPING_EXTEND(7) SmokePing SMOKEPING_EXTEND(7)
2
6 smokeping_extend - Notes on extending Smokeping
7
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 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
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 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
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
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 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 The special sections "synopsis" and "variables" are automatically
52 generated from the description of your variables. See below.
53 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 my $e = "=";
59 my $doc = <<DOC;
60 ${e}head1 SECTION TITLE
61 DOC
62
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
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 (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 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 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 sub probevars {
92 my $class = shift;
93 return $class->_makevars($class->SUPER::probevars, {
94 # your variables go here
95 }
96 }
97 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 For reference, here are the keys the hash should have. Much of this is
105 taken straight from the "Config::Grammar" manual.
106 Keys you must provide
108 _doc
109 Description of the variable.
110 _example
112 An example value. This will be used in the SYNOPSIS section in
113 the probe manual.
114 Optional keys
116 _default
117 A default value that will be assigned to the variable if none
118 is specified or inherited.
119 _re Regular expression upon which the value will be checked.
121 _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 _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 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
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
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 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 You should return a sorted array of the latency times measured. If a
161 ping fails, don't put anything in the array.
162 That's it, you're done!
164
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 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
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 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 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 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 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
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 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 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
228 Niko Tyni <ntyni@iki.fi>
229
231 This document makes writing new probes look much harder than it really
232 is.
233
235 The other Smokeping documents, especially smokeping_config.
2362.7.2 2011-10-07 SMOKEPING_EXTEND(7)