source: trunk/noc/ng/README.map @ 1850

Last change on this file since 1850 was 42, checked in by presbrey, 17 years ago
scripts.mit.edu NOC graphing
File size: 3.4 KB
Line 
1map file
2--------
3
4File:    $Id: README.map,v 1.3 2005/10/08 05:55:08 sauber Exp $
5Author:  (c) Soren Dossing, 2005
6License: OSI Artistic License
7         http://www.opensource.org/licenses/artistic-license.php
8
9This describes how to work with the map file.
10
11The file called 'map' contains regular expressions to identify services
12and define content in RRD databases. All entries are written in perl, so
13editing, adding or deleting entries requires some perl programming
14knowledge. Knowledge of RRD is also necessary.
15
16There has to be one entry for each type of service. The distributed map
17file already have several examples for cpu, memory, disk, network etc.
18Most examples follow the same schema of identifying data from either
19Nagios output or Nagios perfdata and defining a number of rrd data
20sources.
21
22insert.pl is the script receiving data from Nagios. It format data for map
23file by creating one string consisting of three lines of text. This string
24might look like this:
25
26  servicedesc:ping
27  output:PING OK - Packet loss = 0%, RTA = 0.00 ms
28  perfdata:
29
30Or like this:
31
32  servicedescr:CPU Load
33  output:OK - load average: 0.06, 0.12, 0.10
34  perfdata:load1=0;15;30;0 load5=0;10;25;0 load15=0;5;20;0
35
36perfdata is not always set, so depending on type of service, the most
37useful data can be in either the output or perfdata line.
38
39For the ping example above, data can be extracted from the output line
40with a regular expression like this:
41
42  /output:PING.*?(\d+)%.+?([.\d]+)\sms/
43
44In this case, two values are extracted and available in $1 and $2. We can
45then create a data structure describing the content of the database. The
46general format is
47
48  [ db-name,
49    [ DS-name, TYPE, DS-value ],
50    [ DS-name, TYPE, DS-value ],
51    ...
52  ]
53
54Where DS-name is the name that will be assigned to a line showing on rrd
55graphs. TYPE is either GAUGE or DERIVE. the DS value is the data
56extracted in the regular expression. The DS value can be an expression,
57for example to normalize to SI units.
58
59Each database definition must be added to the @s array.
60
61So the complete code to define and insert into and rrd database for the
62PING example above, becomes:
63
64  /output:PING.*?(\d+)%.+?([.\d]+)\sms/
65  and push @s, [ ping,
66                [ losspct, GAUGE, $1      ],
67                [ rta,     GAUGE, $2/1000 ] ];
68
69In this case the database name is called 'ping' and the DS-names stored
70are losspct and rta. The Nagios output reports round trip time in
71milliseconds, so the value is multiplied by 1000 to convert to seconds.
72Both DS type are GAUGE.
73
74Be careful about the database names and DS names. In the code example
75above the names are barewords, which only works as long as the don't
76conflict with perl functions or subroutines. For example the word 'sleep'
77will not work without quoting.
78
79A safer version of the above example is
80
81  /output:PING.*?(\d+)%.+?([.\d]+)\sms/
82  and push @s, [ 'ping',
83                [ 'losspct', 'GAUGE', $1      ],
84                [ 'rta',     'GAUGE', $2/1000 ] ];
85
86After editing map file, the syntax can be checked with
87
88  perl -c map
89
90Again a word of caution. If map file has syntax errors, nothing will be
91inserted into rrd files until the file is fixed. So don't edit production
92map files. Instead do something like this:
93
94  cp map map.edit
95  vi map.edit
96  perl -c map.edit
97  mv map.edit map
98
99Share your work. If you have a good map file entry for standard Nagios
100plugins, then please post it on the forum, or send it to me.
Note: See TracBrowser for help on using the repository browser.