NAME
RRD::Simple - Simple interface to create and store data in RRD files
SYNOPSIS
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 DESCRIPTION
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.
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.
METHODS
new
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.
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.
create
$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).
$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.
update
$rrd->update($rrdfile, $unixtime,
source_name => 'VALUE',
source_name => 'VALUE',
source_name => 'VALUE'
);$rrdfile is optional and will default to $0.rrd. (Script basename with the file extension of .rrd).
$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.
last
my $unixtime = $rrd->last($rrdfile);$rrdfile is optional and will default to $0.rrd. (Script basename with the file extension of .rrd).
sources
my @sources = $rrd->sources($rrdfile);$rrdfile is optional and will default to $0.rrd. (Script basename with the file extension of .rrd).
add_source
$rrd->add_source($rrdfile,
source_name => 'TYPE'
);$rrdfile is optional and will default to $0.rrd. (Script basename with the file extension of .rrd).
graph
$rrd->graph($rrdfile,
destination => '/path/to/write/graph/images',
rrd_graph_option => 'value',
rrd_graph_option => 'value',
rrd_graph_option => 'value'
);$rrdfile is optional and will default to $0.rrd. (Script basename with the file extension of .rrd).
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).
Common RRD graph options are:
- "title"
-
A horizontal string at the top of the graph.
- "vertical-label"
-
A vertically placed string at the left hand side of the graph.
- "width"
-
The width of the canvas (the part of the graph with the actual data and such). This defaults to 400 pixels.
- "height"
-
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.
VARIABLES
$RRD::Simple::DEBUG
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.
$RRD::Simple::DEFAULT_DSTYPE
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.
TODO
Finish POD.
Write the retention duration scheme handling code. (Currently defaults to one year retention only).
Write info() and fetch() methods.
SEE ALSO
RRDTool::Managed, RRDTool::OO, RRD::Query, RRDs, http://www.rrdtool.org, examples/*.pl
VERSION
$Id: Simple.pm,v 1.13 2005/12/10 15:56:22 nicolaw Exp $
AUTHOR
Nicola Worthington <nicolaw@cpan.org>
COPYRIGHT
(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