perf2rrd


COPYRIGHT (C) 2004 Marc DeTrano and Gridshield S.A.


System Requirements:



-Java runtime environment 1.5.0 or higher.
    http://java.sun.com

-RRDTool, with development libraries.
    http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/

-Nagios(R) 1.x, 2.x, or 3.x configured to output performance data to file or pipe.
    http://www.nagios.org/

(if using Nagios 2.x or higher, the object_cache_file directive must also be set).

-The Nagios performance data template must be defined in the Nagios configuration with tab (\t) delimiters
The template must include these macros: $TIMET$ , $HOSTNAME$ , $SERVICEDESC$ , $PERFDATA$ (or $SERVICEPERFDATA$ if Nagios 2 or higher)
If you just use the default template included with Nagios you should be set.

-Nagios plugins that provide performance data in the standard format as shown in the developer guidelines:
    http://nagiosplug.sourceforge.net/developer-guidelines.html

Namely...
    'label'=value[UOM];[warn];[crit];[min];[max]

--perf2rrd will support reading from a named pipe, and this is recommended if running as daemon with Nagios 2 or higher.
set service_perfdata_file_mode=w (or 'p' in Nagios 3) in nagios.cfg
after this is set, the pipe MUST be manually created with mkfifo {name of service_perfdata_file)
make sure the nagios user has write access to the pipe.


* Nagios is a registered trademark of Ethan Galstad.

Installing:



see doc/INSTALL in the source package for installation instructions.

Running:


Foreground (useful for testing)...


- execute the "run" script in perf2rrd_root

- edit the run script if needed.

Usage:
   -h Help
   -c Nagios Config File (defaul /etc/nagios/nagios.cfg)
   -n Nagios Command File (default /usr/sbin/nagios)
   -d RRD Repository Dir (default /var/log/nagios/rrd)
   -x Debug mode on
   -o Process perfdata file only once, then exit
   -p Data points per time period (default 500)
   -t Comma separated list of time periods for RRAs, given as days. ( default 7,31,180 )

Note: One RRA is always created to store all datapoints collected in 24 hours. When considering time periods and data points for additional RRAs, think about what kind of graphs you would like from the RRD files.

Example: setting data points to 500 (the default) and a time period of 180 (days), will produce an RRA that can be used to create a graph 500 pixels wide showing data from the past 6 months. To avoid "blocky" graphs due to shortage of data points, perf2rrd will actually create 25% more rows in an RRA than the number of data points specified.


As a daemon...


-see the Daemonizing section in doc/INSTALL


Called from Nagios (Nagios 2.x or higher ONLY)...


define a command similar to the following:

# process perfdata file
define command {
    command_name perf2rrd
    command_line {perf2rrd_root}/run -o
}

(the -o flag tells perf2rrd to only process the file once, then exit)

In the main nagios.cfg,
   service_perfdata_file=/var/log/nagios/perfdata.pipe
   service_perfdata_file_template=[SERVICEPERFDATA]\t$TIMET$\t$HOSTNAME$\t$SERVICEDESC$\t$SERVICEEXECUTIONTIME$\t$SERVICELATENCY$\t$SERVICEOUTPUT$\t$SERVICEPERFDATA$
   service_perfdata_file_mode=a
   service_perfdata_file_processing_command=perf2rrd
   service_perfdata_file_processing_interval=10
(Note: host perfdata processing is not yet implemented in perf2rrd).

Compiling:


-Get Java SDK 1.5.0 (http://java.sun.com) or higher, make sure javac is in the "PATH".

-execute "compile" script in the root of the installation.

-see doc/INSTALL if you need to recompile the libjrrd.so JNI

What does it do?




What does it NOT do?


Graph the data.

perf2rrd handles one step and one step only: to get data from Nagios to RRD files. It tries to do this in a way that requires the least amount of special configuration possible. The trade off is that the Nagios plugins MUST provide data according to the standard in the developer's guidelines. The latest plugin packages show increasing support for this. You still may need to customize some plugins--rewrite code, or create wrapper scripts--to get the perfdata needed.


How should I graph the data?