RRD::Simple - Simple interface to create and store data in RRD files
use strict; use RRD::Simple (); # Create an interface object my $rrd = RRD::Simple->new(); # Create a new RRD file with 3 data sources called # bytesIn, bytesOut and faultsPerSec. $rrd->create("myfile.rrd", bytesIn => "GAUGE", bytesOut => "GAUGE", faultsPerSec => "COUNTER" ); # Put some arbitary data values in the RRD file for same # 3 data sources called bytesIn, bytesOut and faultsPerSec. $rrd->update("myfile.rrd", bytesIn => 10039, bytesOut => 389, faultsPerSec => 0.4 ); # Generate graphs my @rtn = $rrd->graph("myfile.rrd", destination => "/var/tmp", title => "Network Interface eth0", "vertical-label" => "Bytes/Faults", "interlaced" => "" ); # Get unixtime of when RRD file was last updated my $lastUpdated = $rrd->last("myfile.rrd"); print "myfile.rrd was last updated at " . scalar(localtime($lastUpdated)) . "\n"; # Get list of data source names from an RRD file my @dsnames = $rrd->sources("myfile.rrd"); print "Available data sources: " . join(", ", @dsnames) . "\n"; # And for the ultimately lazy, you could create and update # an RRD in one go using a one-liner like this: perl -MRRD::Simple -e'RRD::Simple->update(@ARGV)' myfile.rrd bytesIn 99999
RRD::Simple provides a simple interface to RRDTool's RRDs module. This module does not currently offer fetch or info methods that are available in the RRDs module.
fetch
info
It does however create RRD files with a sensible set of default RRA (Round Robin Archive) definitions, and can dynamically add new data source names to an existing RRD file.
This module is ideal for quick and simple storage of data within an RRD file if you do not need to, nor want to bother defining custom RRA definitions.
my $rrd = RRD::Simple->new( rrdtool => '/usr/local/rrdtool-1.2.11/bin/rrdtool' );
The rrdtool paramater is optional. It specifically defines where the rrdtool binary can be found. If not specified, the module will search for the rrdtool binary in your path, and an additional location relative where the RRDs module was loaded from.
rrdtool
RRDs
The rrdtool binary is only used by the add_source method, which could also be automatically called by the update method if data point values for a previous undefined data source are provided for insertion.
add_source
update
$rrd->create($rrdfile, $period, source_name => 'TYPE', source_name => 'TYPE', source_name => 'TYPE' );
$rrdfile is optional and will default to $0.rrd. (Script basename with the file extension of .rrd).
$rrdfile
$0.rrd
$period is optional and will default to year. Valid options are day, week, month, year and 3years. Specifying a retention period value will change how long data will be retained for within the RRD file.
$period
year
day
week
month
3years
$rrd->update($rrdfile, $unixtime, source_name => 'VALUE', source_name => 'VALUE', source_name => 'VALUE' );
$unixtime is optional and will default to time() (the current unixtime). Specifying this value will determine the date and time that your data point values will be stored against in the RRD file.
$unixtime
time()
my $unixtime = $rrd->last($rrdfile);
my @sources = $rrd->sources($rrdfile);
$rrd->add_source($rrdfile, source_name => 'TYPE' );
$rrd->graph($rrdfile, destination => '/path/to/write/graph/images', rrd_graph_option => 'value', rrd_graph_option => 'value', rrd_graph_option => 'value' );
The destination paramater is optional, and it will default to the same path location as that of the RRD file specified by $rrdfile. Specifying this value will force the resulting graph images to be written to this path location. (The specified path must be a valid directory with the sufficient permissions to write the graph images).
destination
Common RRD graph options are:
A horizontal string at the top of the graph.
A vertically placed string at the left hand side of the graph.
The width of the canvas (the part of the graph with the actual data and such). This defaults to 400 pixels.
The height of the canvas (the part of the graph with the actual data and such). This defaults to 100 pixels.
For examples on how to best use the graph method, refer to the example scripts that are bundled with this module in the examples/ directory. A complete list of paramaters can be found at http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/doc/index.en.html.
graph
Debug and trace information will be printed to STDERR if this variable if set to boolean true.
This variable will take it's value from $ENV{DEBUG}, if it exists, otherwise it will default to 0 (boolean off). This is a normal package variable and may be safely modified at any time.
$ENV{DEBUG}
0
This variable is used as the default data source type when creating or adding new data sources, when no other data source type is explicitly specified.
This variable will take it's value from $ENV{DEFAULT_DSTYPE}, if it exists, otherwise it will default to GAUGE. This is a normal package variable and may be safely modified at any time.
$ENV{DEFAULT_DSTYPE}
GAUGE
Finish POD.
Write the retention duration scheme handling code. (Currently defaults to one year retention only).
Write info() and fetch() methods.
RRDTool::Managed, RRDTool::OO, RRD::Query, RRDs, http://www.rrdtool.org, examples/*.pl
$Id: Simple.pm,v 1.13 2005/12/10 15:56:22 nicolaw Exp $
Nicola Worthington <nicolaw@cpan.org>
http://perlgirl.org.uk
(c) Nicola Worthington 2005. This program is free software; you can redistribute it and/or modify it under the GNU GPL.
See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt
To install RRD::Simple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm RRD::Simple
CPAN shell
perl -MCPAN -e shell install RRD::Simple
For more information on module installation, please visit the detailed CPAN module installation guide.