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?
- Polls the nagios perfdata output file every 10 seconds, or continuously if using the named-pipe output method (i.e service_perfdata_file_mode=w)
- Reads the contents of that file into memory, then clears and releases the file. In named-pipe mode, waits for a line of input from the fifo.
- Each line of perfdata input will have a host, service description, and one or more items of performance data.
- For each item of performance data, an RRD file will be created, if it does not already exist.
- The RRD files are stored in the repository (default /var/log/nagios/rrd) with the name: {hostname}+{service description}+{perfdata variable name}.rrd (Spaces in service descriptions or perfdata variable names will be replaced with underscores in the filename.)
- Because of this naming convention, the plus sign '+' must not be used in host_name's or service_description' in Nagios. I recommend adding it to the list of invalid characters in the configs.
- There is one DS per file, named 'val'.
- The step interval is set to be the normal_check_interval for the service (parsed from the Nagios configuration, or in Nagios 2 or higher from object_cache_file).
- If the UOM field from the perfdata is 'c', then the type for this DS will be COUNTER, if it is anything else, or not present, the type will be GAUGE.
- The min and max values for the DS will be taken from the min and max values in the perfdata output. If not given, they will be undefined (no min or max).
- If the UOM is '%', then the min and max values will be 0 to 100, unless explicitly stated otherwise in the perfdata output.
- A number of RRA's will be created for 'val'. One RRA will contain MIN, MAX, and AVG values for all datapoints collected in the past 24 hours. By default, additional RRAs are setup to provide 500 points of information for graphing AVG, MIN, or MAX for time periods of 1 week, 1 month, or 6 months. These time periods and graph resolutions can now be overridden with the -p and -t flags.
- Once the RRD files have been created, perf2rrd will continuously update them with the data output by Nagios.
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?
- Well, I use DRRAW, and highly
recommend it.
- You can always read up on 'rrdtool graph' and create your own system, or make life easy and use DRRAW.
- (even if you use DRRAW you should read up on 'rrdtool graph').
- the rest is left as an exercise for the reader.