torrus/doc/devdoc/wd.monitor-escalation.pod

   1 #  Copyright (C) 2002  Stanislav Sinyagin
   2 #
   3 #  This program is free software; you can redistribute it and/or modify
   4 #  it under the terms of the GNU General Public License as published by
   5 #  the Free Software Foundation; either version 2 of the License, or
   6 #  (at your option) any later version.
   7 #
   8 #  This program is distributed in the hope that it will be useful,
   9 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 #  GNU General Public License for more details.
  12 #
  13 #  You should have received a copy of the GNU General Public License
  14 #  along with this program; if not, write to the Free Software
  15 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  16
  17 # $Id: wd.monitor-escalation.pod,v 1.1 2010-12-27 00:04:36 ivan Exp $
  18 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  19 #
  20 #
  21
  22 =head1 RRFW Working Draft: Monitor escalation levels
  23
  24 Status: pending implementation.
  25 Date: Nov 5 2003. Last revised: Nov 10 2003
  26
  27 =head2 Introduction
  28
  29 The initial idea comes from Francois Mikus in Cricket development team.
  30 His proposal was to raise the alarm only after several true consecutive
  31 monitor conditions.
  32
  33 The idea has developed into the concept of escalation levels.
  34
  35
  36 =head2 Monitor events
  37
  38 Current implementation supports four types of monitor events: C<set>,
  39 C<repeat>, C<clear>, and C<forget>. New event type will be C<escalate(X)>.
  40 C<X> designates a symbolic name for a certain escalation level. Each level
  41 is associated with the escalation time interval.
  42
  43 Given C<Te> as the escalation interval, C<Ta> as the monitor condition age,
  44 and C<P> as period, the escalation event will occur simultaneously with
  45 one of C<repeat> events, when the following condition is true:
  46
  47   Te >= Ta
  48
  49 New event types C<clear(X)> and C<forget(X)> will occur at the same
  50 time as C<clear> and C<forget> respectively,
  51 for each escalated level.
  52
  53
  54 =head2 Monitor parameters
  55
  56 New parameter will be introduced: C<escalation>. Value will
  57 be a comma-separated list of C<name=interval> parts, where C<name>
  58 designates the escalation level, and C<interval> specifies the escalation
  59 interval in seconds.
  60
  61 Example:
  62
  63   <monitor name="rate-limits">
  64     <param name="escalation value="Medium=1800, High=7200, Critical=14400" />
  65     ...
  66   </monitor>
  67
  68 Another example would be Cisco TAC style priorities: P3, P2, P1.
  69
  70
  71 =head2 Action parameters
  72
  73 C<launch-when> parameter will be valid not for C<exec> actions only, but also
  74 for C<tset> actions. New valid values will be C<escalate(X)>, C<clear(X)>,
  75 and C<forget(X)>.
  76
  77 XML configuration validator will not verify if escalation levels in
  78 action definition match those in datasource configuration.
  79
  80 New optional action parameter: C<allowed-time>. Contains an RPN expression
  81 which must be true at the time when the action is allowed to execute.
  82 Two new RPN functions may be used here: C<TOD> and C<DOW>.
  83
  84 C<TOD> returns the current time of day as integer: C<HH*100+MM>. For example,
  85 830 means 8:30 AM, and 1945 means 7:45 PM.
  86
  87 C<DOW> returns the current day of the week as integer between and including
  88 0 and 6, with 0 corresponding to Sunday, 1 to Monday, and 6 to Saturday.
  89
  90 In this example, the action is allowed between 8 AM and 6 PM from Monday
  91 to Friday:
  92
  93   <param name="allowed-time">
  94     TOD,800,GE, TOD,1800,LE, AND,
  95     DOW,1,GE, AND,
  96     DOW,5,LE, AND
  97   </param>
  98
  99
 100 =head2 Implementation
 101
 102 B<monitor_alarms.db> database format will change: The values will consist
 103 of five colon-separated fields. The first four fields will be as earilier,
 104 and the fifth one will be a comma-separated list of escalation level names
 105 that have already fired.
 106
 107 The implementation of this feature is preferred after the planned redesign of
 108 the monitor daemon. The new monitor design would support individual
 109 schedule for each datasource leaf, analogous to collector schedules.
 110
 111 In turn, the monitor daemon  redesign is better to do after
 112 the collector daemon redesign. Then it would allow to keep similar design
 113 and architecture where possible.
 114
 115 =head1 Author
 116
 117 Copyright (c) 2003 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>