torrus/doc/manpages/torrus_snmpfailures.pod.in

   1 #  Copyright (C) 2010  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: torrus_snmpfailures.pod.in,v 1.1 2010-12-27 00:04:37 ivan Exp $
  18 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  19 #
  20 #
  21
  22 =head1 NAME
  23
  24 snmpfailures - Displays SNMP collector failures.
  25
  26 =head1 SYNOPSIS
  27
  28 B<torrus snmpfailures> --tree=I<TREENAME> [I<options...>]
  29
  30 =head1 OPTIONS
  31
  32 =over 4
  33
  34 =item B<--details>
  35
  36 In addition to failure counters, list the failed SNMP hosts and the time
  37 stamps of failure events.
  38
  39
  40 =item B<--help>
  41
  42 Displays a help message.
  43
  44 =back
  45
  46 =head1 DESCRIPTION
  47
  48 This utility prints the SNMP collector failure information in JSON format.
  49 Without B<--details> option, it prints only the failure counters.
  50
  51 Upon collector startup or after the tree re-compilation, the failure
  52 counters are reset to zero.
  53
  54 The output is very convenient for further automatic processing in any
  55 scripting language.
  56
  57 The top level of the output is a JSON object with the following name/value
  58 pairs:
  59
  60 =over 4
  61
  62 =item B<total_unreachable>: NUMBER
  63
  64 Displays the number SNMP hosts that are currently unreachable.
  65 The number adds up across multiple collector instances for a given tree.
  66 If a host becomes reachable again, the number is decreased.
  67
  68 =item B<total_deleted>: NUMBER
  69
  70 Displays the number SNMP hosts that are completely removed from SNMP
  71 collection for the life cycle of the collector process. This happens when
  72 a host is unreachable for too long time and the collector gives up
  73 to reach it again.
  74 The number adds up across multiple collector instances for a given tree.
  75
  76 =item B<total_mib_errors>: NUMBER
  77
  78 Displays the number of MIB errors (I<noSuchObject>, I<noSuchInstance>,
  79 and I<endOfMibView>) during the collector life cycle.
  80 The number adds up across multiple collector instances for a given tree.
  81
  82 =item B<detail_unreachable>: OBJECT, B<detail_deleted>: OBJECT
  83
  84 If the option B<--details> is specified, these objects contain the host names
  85 and timestamps of the failures.
  86 The keys are contactenations of SNMP host, UDP port, and SNMP
  87 community separated by "|".
  88 The values are objects representing the UNIX timestamp and a human-readable
  89 time string.
  90
  91 =item B<detail_mib_errors>: OBJECT
  92
  93 If the option B<--details> is specified, this object displays the MIB error
  94 details: for each SNMP host, it lists the datasource leaves which had these
  95 errors and the event timestamps.
  96
  97 =back
  98
  99 =head1 EXAMPLES
 100
 101 The following example illustrates an SNMP host unreachable:
 102
 103  torrus failures --tree=main --details
 104  {
 105     "detail_deleted" : {},
 106     "detail_mib_errors" : {},
 107     "detail_unreachable" : {
 108        "217.101.101.101|161|public" : {
 109           "time" : "Fri Jul 23 14:15:10 2010",
 110           "timestamp" : 1279887310
 111        }
 112     },
 113     "total_deleted" : 0,
 114     "total_mib_errors" : 0,
 115     "total_unreachable" : 1
 116  }
 117
 118
 119 The following example illustrates a MIB error:
 120
 121  torrus failures --tree=main --details
 122  {
 123     "detail_deleted" : {},
 124     "detail_mib_errors" : {
 125        "217.101.102.102|161|public" : {
 126           "count" : 1,
 127           "nodes" : {
 128              "/Routers/CMTS3/Temperature_Sensors/sensor_01" : {
 129                 "time" : "Fri Jul 23 15:26:14 2010",
 130                 "timestamp" : 1279891574
 131              }
 132           }
 133        }
 134     },
 135     "detail_unreachable" : {},
 136     "total_deleted" : 0,
 137     "total_mib_errors" : 1,
 138     "total_unreachable" : 0
 139  }
 140
 141
 142
 143
 144
 145 =head1 SEE ALSO
 146
 147 L<torrus(@mansec_usercmd@)>,
 148
 149 =head1 NOTES
 150
 151 See more documentation at Torrus home page: http://torrus.org
 152
 153 =head1 AUTHOR
 154
 155 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>