map file
--------

File:    $Id$
Author:  (c) Soren Dossing, 2005
License: OSI Artistic License
         http://www.opensource.org/licenses/artistic-license.php

This describes how to work with the map file.

The file called 'map' contains regular expressions to identify services 
and define content in RRD databases. All entries are written in perl, so 
editing, adding or deleting entries requires some perl programming 
knowledge. Knowledge of RRD is also necessary.

There has to be one entry for each type of service. The distributed map 
file already have several examples for cpu, memory, disk, network etc.
Most examples follow the same schema of identifying data from either 
Nagios output or Nagios perfdata and defining a number of rrd data 
sources.

insert.pl is the script receiving data from Nagios. It format data for map 
file by creating one string consisting of three lines of text. This string 
might look like this:

  servicedesc:ping
  output:PING OK - Packet loss = 0%, RTA = 0.00 ms
  perfdata:

Or like this:

  servicedescr:CPU Load 
  output:OK - load average: 0.06, 0.12, 0.10
  perfdata:load1=0;15;30;0 load5=0;10;25;0 load15=0;5;20;0 

perfdata is not always set, so depending on type of service, the most 
useful data can be in either the output or perfdata line.

For the ping example above, data can be extracted from the output line 
with a regular expression like this:

  /output:PING.*?(\d+)%.+?([.\d]+)\sms/

In this case, two values are extracted and available in $1 and $2. We can 
then create a data structure describing the content of the database. The 
general format is

  [ db-name,
    [ DS-name, TYPE, DS-value ],
    [ DS-name, TYPE, DS-value ],
    ...
  ]

Where DS-name is the name that will be assigned to a line showing on rrd 
graphs. TYPE is either GAUGE or DERIVE. the DS value is the data 
extracted in the regular expression. The DS value can be an expression, 
for example to normalize to SI units.

Each database definition must be added to the @s array.

So the complete code to define and insert into and rrd database for the 
PING example above, becomes:

  /output:PING.*?(\d+)%.+?([.\d]+)\sms/
  and push @s, [ ping,
                [ losspct, GAUGE, $1      ],
                [ rta,     GAUGE, $2/1000 ] ];

In this case the database name is called 'ping' and the DS-names stored 
are losspct and rta. The Nagios output reports round trip time in 
milliseconds, so the value is multiplied by 1000 to convert to seconds. 
Both DS type are GAUGE.

Be careful about the database names and DS names. In the code example 
above the names are barewords, which only works as long as the don't 
conflict with perl functions or subroutines. For example the word 'sleep' 
will not work without quoting.

A safer version of the above example is

  /output:PING.*?(\d+)%.+?([.\d]+)\sms/
  and push @s, [ 'ping',
                [ 'losspct', 'GAUGE', $1      ],
                [ 'rta',     'GAUGE', $2/1000 ] ];

After editing map file, the syntax can be checked with

  perl -c map

Again a word of caution. If map file has syntax errors, nothing will be 
inserted into rrd files until the file is fixed. So don't edit production 
map files. Instead do something like this:

  cp map map.edit
  vi map.edit
  perl -c map.edit
  mv map.edit map

Share your work. If you have a good map file entry for standard Nagios 
plugins, then please post it on the forum, or send it to me.