Threshold.pm untested

filter: Statementstmt 0.0% 0 / 94 Branchbran 0.0% 0 / 52 Conditioncond 0.0% 0 / 37 MC/DCmcdc 0.0% 0 / 23 Subroutinesub 0.0% 0 / 12 Podpod 0.0% 0 / 8 totaltotal 0.0% 0 / 226 CC 27 SCAR 48.3
CC
27
Cov
0%
_relation
272.0
boundaries
30.0
hunt
30.0
CRAP 124.9
1 package RRD::Threshold;
2  
3 use strict;
4 use RRD::Query qw(isNaN);
5 use Error qw(:try);
6  
7 # $Id: Threshold.pm,v 1.9 2004/12/07 12:53:56 rs Exp $
8 $RRD::Threshold::VERSION = sprintf "%d.%03d", q$Revision: 1.9 $ =~ /(\d+)/g;
9  
10 =pod
11  
12 =head1 NAME
13  
14 RRD::Threshold - Check for thresholds exceeding values in RRD files data
15  
16 =head1 DESCRIPTION
17  
18 This Perl module is capable of extracting some RRD information and to
19 detect if the current value of a datasource is exeeding some
20 thresholds using different algorithms and the help of past values of
21 the same or other datasource.
22  
23 =head1 CONSTRUCTOR
24  
25 The constructor takes no arguments.
26  
27 =cut
28  
29 sub new
30 {
31 my $proto = shift();
32 my $class = ref($proto) || $proto;
33 my $self = bless({}, $class);
34 return $self;
35 }
36  
37 =pod
38  
39 =head1 METHODS
40  
41 =head2 boundaries
42  
43 ($value, $bool) = boundaries($rrdfile, $ds, min => $min, max => $max)
44  
45 This threshold takes too optional values, a minimum and a maximum
46 value. If the data source strays outside of this interval, it returns
47 false.
48  
49 =head3 Options
50  
51 =over 4
52  
53 =item rrdfile
54  
55 The path to the RRD file
56  
57 =item ds
58  
59 The name of the datasource. If the datasource contains comat (,), your
60 datasource will be interpreted as an RPN (Reverse Polish Notation)
61 expression (see L<Math::RPN>). If the C<Math::RPN> module isn't
62 loadable, an C<Error::RRD::Feature> exception is thrown.
63  
64 Some valide examples of datasource would be: C<ifError>,
65 C<high_mem,low_mem,+>.
66  
67 =item min
68  
69 If current value is lower than this argument, the function returns
70 false.
71  
72 =item max
73  
74 If current value is greater than this argument, the function returns
75 false.
76  
77 =back
78  
79 =head3 Throws
80  
81 =over 4
82  
83 =item Error::InvalidArgument
84  
85 If min is greater than max
86  
87 =item Error::RRDs
88  
89 on RRDs library error
90  
91 =item Error::RRD::isNaN
92  
93 if fetched value is Not a Number
94  
95 =item Error::RRD::NoSuchDS
96  
97 if the given datasource can't be found in the RRD file
98  
99 =back
100  
101 =cut
102  
103 sub boundaries
104 {
105 my($self, $rrdfile, $ds, %args) = @_;
106 my($min, $max) = @args{qw(min max)};
107  
108 if(defined $min and defined $max && $min > $max)
109 {
110 throw Error::InvalidArgument("Min can't be greater than max value");
111 }
112  
113 my $value;
114 my $rrd = new RRD::Query($rrdfile);
115 $value = $rrd->fetch($ds);
116  
117 if(isNaN($value))
118 {
119 throw Error::RRD::isNaN("Current value is NaN");
120 }
121  
122 if(defined $min && $value < $min)
123 {
124 return($value, 0);
125 }
126  
127 if(defined $max && $value > $max)
128 {
129 return($value, 0);
130 }
131  
132 return($value, 1);
133 }
134  
135 =pod
136  
137 =head2 exact
138  
139 ($value, $bool) = exact($rrdfile, $ds, $exact)
140  
141 This threshold allows you to monitor a datasource for an exact
142 match. This is useful in cases where an enumerated (or boolean) SNMP
143 object instruments a condition where a transition to a specific state
144 requires attention. For example, a datasource might return either
145 true(1) or false(2), depending on whether or not a power supply has
146 failed.
147  
148 =head3 Options
149  
150 =over 4
151  
152 =item rrdfile
153  
154 The path to the RRD file
155  
156 =item ds
157  
158 The name of the datasource. If the datasource contains comat (,), your
159 datasource will be interpreted as an RPN (Reverse Polish Notation)
160 expression (see L<Math::RPN>). If the C<Math::RPN> module isn't
161 loadable, an C<Error::RRD::Feature> exception is thrown.
162  
163 Some valide examples of datasource would be: C<ifError>,
164 C<high_mem,low_mem,+>.
165  
166 =item exact
167  
168 If the current value is different than this argument, the function
169 will return false.
170  
171 =back
172  
173 =head3 Throws
174  
175 =over 4
176  
177 =item Error::InvalidArgument
178  
179 if exact argument isn't given
180  
181 =item Error::RRDs
182  
183 on RRDs library error
184  
185 =item Error::RRD::isNaN
186  
187 if fetched value is Not a Number
188  
189 =item Error::RRD::NoSuchDS
190  
191 if the given datasource can't be found in the RRD file
192  
193 =back
194  
195 =cut
196  
197 sub exact
198 {
199 my($self, $rrdfile, $ds, $exact) = @_;
200  
201 if(!defined($exact))
202 {
203 throw Error::InvalidArgument("Missing mandatory option: exact");
204 }
205  
206 my $rrd = new RRD::Query($rrdfile);
207 my $value = $rrd->fetch($ds);
208  
209 if(isNaN($value))
210 {
211 throw Error::RRD::isNaN("Current value is NaN");
212 }
213  
214 return($value, $exact == $value ? 1 : 0);
215 }
216  
217 =pod
218  
219 =head2 relation
220  
221 ($value, $bool) = relation($rrdfile, $ds, $threshold, %args,
222 cmp_rrdfile => $cmp_rrdfile,
223 cmp_ds => $cmp_ds,
224 cmp_timp => $cmp_time);
225  
226  
227 A relation threshold considers the difference between two data sources
228 (possibly from different RRD files), or alternatively, the difference
229 between two temporally distinct values for the same data source. The
230 difference can be expressed as absolute value, or as a percentage of
231 the second data source (comparison) value. This difference is compared
232 to a threshold argument with either the greater than (>) or lesser
233 than (<) operator. The criteria fails when the expression (<absolute
234 or relative difference> <either greater-than or less-than>
235 <threshold>) evaluates to false.
236  
237 =head3 Options
238  
239 =over 4
240  
241 =item rrdfile
242  
243 The path of the base RRD file.
244  
245 =item ds
246  
247 The name of the base datasource. The data source must belong to the
248 $rrdfile. If the datasource contains comat (,), your datasource will
249 be interpreted as an RPN (Reverse Polish Notation) expression (see
250 L<Math::RPN>). If the C<Math::RPN> module isn't loadable, an
251 C<Error::RRD::Feature> exception is thrown.
252  
253 Some valide examples of datasource would be: C<ifError>,
254 C<high_mem,low_mem,+>.
255  
256 =item threadhold
257  
258 The threshold number, optionally preceded by the greater than (>) or
259 less than (<) symbol, and optionally followed by the symbol percent
260 (%). If omitted, greater than is used by default and the expression,
261 difference > threshold, is evaluated. "<10%", ">1000", "50%", and
262 "500" are all examples of valid thresholds.
263  
264 =item cmp_rrdfile
265  
266 The path of the comparison RRD file. This argument is optional and if
267 omitted the first RRD file is also taken as the comparison target.
268  
269 =item cmp_ds
270  
271 The name of the comparison data source. This data source must belong
272 to the comparison RRD file. This argument is optional and if omitted
273 the first data source name is also taken as the comparison data source
274 name. If the value is a number, the value is considered as a fix
275 value and is taked for the comparison.
276  
277 If the datasource contains comat (,), your datasource will be
278 interpreted as an RPN (Reverse Polish Notation) expression (see
279 L<Math::RPN>). If the C<Math::RPN> module isn't loadable, an
280 C<Error::RRD::Feature> exception is thrown.
281  
282 Some valide examples of datasource would be: C<ifError>,
283 C<high_mem,low_mem,+>, C<10023>, C<-243.23>.
284  
285 =item cmp_time
286  
287 The temporal offset to go back in the RRD file that is being fetched
288 from for comparison from the current value. Note that a data source
289 value must exist in the RRD file for that exact offset. If This
290 argument is optional and if omitted, it is set to 0.
291  
292 =back
293  
294 =head3 Throws
295  
296 =over 4
297  
298 =item Error::InvalidArgument
299  
300 on argument error
301  
302 =item Error::RRDs
303  
304 on RRDs library error
305  
306 =item Error::RRD::isNaN
307  
308 if fetched value is Not a Number
309  
310 =item Error::RRD::NoSuchDS
311  
312 if the given datasource can't be found in the RRD file
313  
314 =back
315  
316 =cut
317  
318 sub relation
319 {
320 shift->_relation(0, @_);
321 }
322  
323 =pod
324  
325 =head2 quotient
326  
327 ($value, $bool) = quotient($rrdfile, $ds, $threshold, %args,
328 cmp_rrdfile => $cmp_rrdfile,
329 cmp_ds => $cmp_ds,
330 cmp_timp => $cmp_time);
331  
332 Quotient thresholds are similar to relation thresholds, except that
333 they consider the quotient of two data sources, or alternatively, the
334 same data source at two different time points. For a quotient monitor
335 threshold, the value of the first data source is computed as a
336 percentage of the second data source value (such as 10 (first
337 datasource) is 50% of 20 (second datasource)). This percentage is then
338 compared to a threshold argument with either the greater than (>) or
339 less than (<) operator. The criteria fails when the expression
340 (<percentage> <either greater-than or less-than> <threshold>)
341 evaluates to false.
342  
343 =head3 Options
344  
345 =over 4
346  
347 =item rrdfile
348  
349 The path of the base RRD file.
350  
351 =item ds
352  
353 The name of the base datasource. The data source must belong to the
354 $rrdfile. If the datasource contains comat (,), your datasource will
355 be interpreted as an RPN (Reverse Polish Notation) expression (see
356 L<Math::RPN>). If the C<Math::RPN> module isn't loadable, an
357 C<Error::RRD::Feature> exception is thrown.
358  
359 Some valide examples of datasource would be: C<ifError>,
360 C<high_mem,low_mem,+>.
361  
362 =item threadhold
363  
364 The threshold number, optionally preceded by the greater than (>) or
365 less than (<) symbol and followed by the symbol percent (%). If
366 omitted, greater than is used by default and the expression,
367 difference > threshold, is evaluated. "<10%" and "50%" are examples of
368 valid thresholds.
369  
370 =item cmp_rrdfile
371  
372 The path of the comparison RRD file. This argument is optional and if
373 omitted the first RRD file is also taken as the comparison target.
374  
375 =item cmp_ds
376  
377 The name of the comparison data source. This data source must belong
378 to the comparison RRD file. This argument is optional and if omitted
379 the first data source name is also taken as the comparison data source
380 name. If the value is a number, the value is considered as a fix
381 value and is taked for the comparison.
382  
383 If the datasource contains comat (,), your datasource will be
384 interpreted as an RPN (Reverse Polish Notation) expression (see
385 L<Math::RPN>). If the C<Math::RPN> module isn't loadable, an
386 C<Error::RRD::Feature> exception is thrown.
387  
388 Some valide examples of datasource would be: C<ifError>,
389 C<high_mem,low_mem,+>, C<10023>, C<-243.23>.
390  
391 =item cmp_time
392  
393 The temporal offset to go back in the RRD file that is being fetched
394 from for comparison from the current value. Note that a data source
395 value must exist in the RRD file for that exact offset. If This
396 argument is optional and if omitted, it is set to 0.
397  
398 =back
399  
400 =head3 Throws
401  
402 =over 4
403  
404 =item Error::InvalidArgument
405  
406 on argument error
407  
408 =item Error::RRDs
409  
410 on RRDs library error
411  
412 =item Error::RRD::isNaN
413  
414 if fetched value is Not a Number
415  
416 =item Error::RRD::NoSuchDS
417  
418 if the given datasource can't be found in the RRD file
419  
420 =back
421  
422 =cut
423  
424 sub quotient
425 {
426 shift->_relation(1, @_);
427 }
428  
429 sub _relation
430 {
431 my($self, $quotient, $rrdfile, $ds, $threshold, %args) = @_;
432 my($cmp_rrdfile, $cmp_ds, $cmp_time) =
433 @args{qw(cmp_rrdfile cmp_ds cmp_time)};
434  
435 if(!defined($threshold) || !($threshold =~ s/^([<>]?)\s*(\d+)\s*(%?)$/$2/))
436 {
437 throw Error::InvalidArgument("Threshold argument syntax error: $threshold");
438 }
439  
440 my $cmp = $1 || '>';
441 my $pct = $3 ? 1 : 0;
442  
443 if($quotient)
444 {
445 if(!$pct)
446 {
447 throw Error::InvalidArgument("Threshold have to be a percentage");
448 }
449 }
450  
451 $cmp_rrdfile ||= $rrdfile;
452 $cmp_ds ||= $ds;
453 $cmp_time ||= 0;
454  
455 my $rrd = new RRD::Query($rrdfile);
456 my $value = $rrd->fetch($ds);
457  
458 if(isNaN($value))
459 {
460 throw Error::Simple("Current value is NaN");
461 }
462  
463 # Test if the comp_ds is a straight comparison value or should be fetched
464 # as a DS
465 my $cmp_value;
466 if($cmp_ds =~ /^[+-]?\d*\.?\d+$/)
467 {
468 $cmp_value = $cmp_ds;
469 }
470 else
471 {
472 my $rrd = new RRD::Query($cmp_rrdfile);
473 $cmp_value = $rrd->fetch($cmp_ds, cf => 'AVERAGE', offset => $cmp_time);
474  
475 if(isNaN($cmp_value))
476 {
477 throw Error::RRD::isNaN("Comparison value is NaN");
478 }
479 }
480  
481 my $difference = abs($cmp_value - $value);
482  
483 # threshold is a percentage
484 if($pct)
485 {
486 # avoid division by 0
487 if($cmp_value == 0)
488 {
489 if($difference == 0 && $cmp eq ($quotient ? '>' : '<'))
490 {
491 return($value, 1);
492 }
493 else
494 {
495 return($value, 0);
496 }
497 }
498  
499 if($quotient)
500 {
501 $difference = $difference / abs($cmp_value) * 100;
502 }
503 else
504 {
505 $difference = abs($value / $cmp_value) * 100;
506 }
507 }
508  
509 if($cmp eq '<')
510 {
511 return($value, $difference < $threshold ? 0 : 1);
512 }
513 else
514 {
515 return($value, $difference > $threshold ? 0 : 1);
516 }
517 }
518  
519 =pod
520  
521 =head2 hunt
522  
523 ($value, $bool) = hunt($rrdfile, $ds, $roll,
524 cmp_rrdfile => $cmp_rrdfile,
525 cmp_ds => $cmp_ds)
526  
527 The hunt threshold is designed for the situation where the data source
528 serves as an overflow for another data source; that is, if one data
529 source (the parent) is at or near capacity, then traffic will begin to
530 appear on this (the monitored) data source. One application of hunt
531 monitor thresholds is to identify premature rollover in a set of modem
532 banks configured to hunt from one to the next. Specifically, the
533 criteria of the hunt monitor threshold fails if the value of the
534 monitored data source is non-zero and the current value of the parent
535 data source falls below a specified capacity threshold.
536  
537 =head3 Option
538  
539 =over 4
540  
541 =item rrdfile
542  
543 The path of the base RRD file.
544  
545 =item ds
546  
547 The name of the base datasource. The data source must belong to the
548 $rrdfile. If the datasource contains comat (,), your datasource will
549 be interpreted as an RPN (Reverse Polish Notation) expression (see
550 L<Math::RPN>). If the C<Math::RPN> module isn't loadable, an
551 C<Error::RRD::Feature> exception is thrown.
552  
553 Some valide examples of datasource would be: C<ifError>,
554 C<high_mem,low_mem,+>.
555  
556 =item roll
557  
558 The threshold of the parent data source. Generally this should be
559 slightly less than the maximum capacity of the target.
560  
561 =item cmp_rrdfile
562  
563 The path of the parent RRD file. This argument is optional and if
564 omitted the base RRD file is also taken as the parent.
565  
566 =item cmp_ds
567  
568 The name of the comparison data source. This data source must belong
569 to the parent RRD file. This argument is optional and if omitted the
570 first data source name is also taken as the comparison data source
571 name.
572  
573 If the datasource contains comat (,), your datasource will be
574 interpreted as an RPN (Reverse Polish Notation) expression (see
575 L<Math::RPN>). If the C<Math::RPN> module isn't loadable, an
576 C<Error::RRD::Feature> exception is thrown.
577  
578 Some valide examples of datasource would be: C<ifError>,
579 C<high_mem,low_mem,+>.
580  
581 =back
582  
583 =head3 Throws
584  
585 =over 4
586  
587 =item Error::InvalidArgument
588  
589 if roll argument isn't given
590  
591 =item Error::RRDs
592  
593 on RRDs library error
594  
595 =item Error::RRD::isNaN
596  
597 if fetched value is Not a Number
598  
599 =item Error::RRD::NoSuchDS
600  
601 if the given datasource can't be found in the RRD file
602  
603 =back
604  
605 =cut
606  
607 sub hunt
608 {
609 my($self, $rrdfile, $ds, $roll, %args) = @_;
610 my($cmp_rrdfile, $cmp_ds) = @args{qw(cmp_rrdfile cmp_ds)};
611  
612 if(!defined($roll))
613 {
614 throw Error::InvalidArgument("Missing mandatory option: roll");
615 }
616  
617 my $cmp_rrdfile ||= $rrdfile;
618 my $cmp_ds ||= $ds;
619  
620 my $rrd = new RRD::Query($rrdfile);
621 my $value = $rrd->fetch($ds);
622  
623 if(isNaN($value))
624 {
625 throw Error::RDD::isNaN("Current value is NaN");
626 }
627  
628 if($value == 0)
629 {
630 # no rollover, test succeeded
631 return($value, 1);
632 }
633  
634 my $rrd = new RRD::Query($cmp_rrdfile);
635 my $cmp_value = $rrd->fetch($cmp_ds);
636  
637 if(isNaN($cmp_value))
638 {
639 throw Error::RRD::isNaN("Hunted value is NaN");
640 }
641  
642 return($value, $cmp_value >= $roll);
643 }
644  
645 =pod
646  
647 =head2 failure
648  
649 Aberrant Behavior Detection failure detection.
650  
651 not yet implemented
652  
653 =cut
654  
655 sub failure
656 {
657 }
658  
659 =pod
660  
661 =head1 EXCEPTIONS CLASSES
662  
663 =head2 Error::InvalidArgument
664  
665 =cut
666  
667 package Error::InvalidArgument;
668  
669 use base qw(Error::Simple);
670  
671 =pod
672  
673 =head1 AUTHOR
674  
675 Olivier Poitrey E<lt>rs@rhapsodyk.netE<gt>
676  
677 =head1 LICENCE
678  
679 RRD::Threshold, checks for thresholds exceeding values in RRD files
680 data.
681 Copyright (C) 2004 Olivier Poitrey
682  
683 This library is free software; you can redistribute it and/or modify
684 it under the terms of the GNU Lesser General Public License as
685 published by the Free Software Foundation; either version 2.1 of the
686 License, or (at your option) any later version.
687  
688 This library is distributed in the hope that it will be useful, but
689 WITHOUT ANY WARRANTY; without even the implied warranty of
690 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
691 Lesser General Public License for more details.
692  
693 You should have received a copy of the GNU Lesser General Public
694 License along with this library; if not, write to the Free Software
695 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
696 USA
697  
698 =head1 SEE ALSO
699  
700 L<RRDs>, L<rrdgraph>, L<RRD::Query>, L<Error>
701  
702 =cut
703  
704 1;