NAME

perfSONAR_PS::DB::RRD - A module that provides methods for dealing with rrd files through the RRDp perl module.

DESCRIPTION

This module builds on the simple offerings of RRDp (simple a series of pipes to communicate with rrd files) to offer some common functionality.

SYNOPSIS

use perfSONAR_PS::DB::RRD;

my $rrd = new perfSONAR_PS::DB::RRD(
  "/usr/local/rrdtool/bin/rrdtool" , 
  "/home/jason/rrd/stout/stout.rrd",
  {'eth0-in'=>"" , 'eth0-out'=>"", 'eth1-in'=>"" , 'eth1-out'=>""},
  1
);

# or also:
# 
# my $rrd = new perfSONAR_PS::DB::RRD;
# $rrd->setFile("/home/jason/rrd/stout/stout.rrd");
# $rrd->setPath("/usr/local/rrdtool/bin/rrdtool");  
# $rrd->setVariables({'eth0-in'=>"" , 'eth0-out'=>"", 'eth1-in'=>"" , 'eth1-out'=>""});  
# $rrd->setVariable("eth0-in");
# ...
# $rrd->setError(1);     

# For reference, here is the create string for the rrd file:
#
# rrdtool create stout.rrd \
# --start N --step 1 \
# DS:eth0-in:COUNTER:1:U:U \ 
# DS:eth0-out:COUNTER:1:U:U \
# DS:eth1-in:COUNTER:1:U:U \
# DS:eth1-out:COUNTER:1:U:U \
# RRA:AVERAGE:0.5:10:60480

# will also 'open' a connection to a file:
if ($rrd->openDB() == -1) {
  print "Error opening database\n";
}

my %rrd_result = $rrd->query(
  "AVERAGE", 
  "", 
  "1163525343", 
  "1163525373"
);

if($rrd->getErrorMessage()) {
  print "Query Error: " , $rrd->getErrorMessage() , "; query returned: " , $rrd_result{ANSWER} , "\n";
}
else {
  my @keys = keys(%rrd_result);
  foreach $a (sort(keys(%rrd_result))) {
    foreach $b (sort(keys(%{$rrd_result{$a}}))) {
      print $a , " - " , $b , "\t-->" , $rrd_result{$a}{$b} , "<--\n"; 
    }
    print "\n";
  }
}

$rrd->insert("N", "eth0-in", "1");
$rrd->insert("N", "eth0-out", "2");
$rrd->insert("N", "eth1-in", "3");
$rrd->insert("N", "eth1-out", "4");
              
my $insert = $rrd->insertCommit();

if($rrd->getErrorMessage()) {
  print "Insert Error: " , $rrd->getErrorMessage() , "; insert returned: " , $insert , "\n";
}

print "last: " , $rrd->lastValue , "\n";
if($rrd->getErrorMessage()) {
  print "last Error: " , $rrd->getErrorMessage() , "\n";
}

print "first: " , $rrd->firstValue , "\n";
if($rrd->getErrorMessage()) {
  print "first Error: " , $rrd->getErrorMessage() , "\n";
}

if ($rrd->closeDB == -1) {
  print "Error closing database\n";
}

DETAILS

RRDp was never meant to a rich API; it's goal is simply to provide a method of interacting with the underlying RRD files. The module is to be treated as an object, where each instance of the object represents a direct connection to a single rrd file. Each method may then be invoked on the object for the specific database.

API

The API of perfSONAR_PS::DB::RRD is rather simple, and attempts to mirror the API of the other perfSONAR_PS::DB::* modules.

new($package, $path, $name, $dss, $error)

The first arguments represents the path to the rrdtool executable, the second represents an actual rrd file. The third can be a hash containing the names of the datasources in the rrd file. The final argument is a boolean indicating if errors should be thrown. All arguments are optional, and the 'set' functions (setLog($log), setFile($file), setPath($path), setVariables(%datasources), setVariables($ds), setError($error)) are capable of setting the information as well.

setFile($self, $file)

Sets the RRD filename.

setPath($self, $path)

Sets the 'path' to the RRD binary.

setVariables($self, $dss)

Sets several variables (in an array) in the RRD.

setVariable($self, $dss)

Sets a variable value in the RRD.

setError($self, $error)

Sets the error variable.

getErrorMessage($self)

Gets any error returned from the underlying RRDp module.

openDB($self)

'Opens' (creates a pipe) to an RRD.

closeDB($self)

'Closes' (terminates the pipe) of an open RRD.

query($self, $cf, $resolution, $start, $end)

Query a RRD with specific times/resolutions.

insert($self, $time, $ds, $value)

'Inserts' a time/value pair for a given variable. These are not inserted into the RRD, but will 'wait' until we commit. This allows us to stack up a bunch of values first. and reuse time values.

insertCommit($self)

'Commits' all outstanding variables time/data pairs for a given RRD.

firstValue($self)

Returns the first value of an RRD

lastValue($self)

Returns the last value of an RRD.

lastTime($self)

Returns the last time the RRD was updated.

SEE ALSO

RRDp, Log::Log4perl, perfSONAR_PS::Common

To join the 'perfSONAR-PS' mailing list, please visit:

https://mail.internet2.edu/wws/info/i2-perfsonar

The perfSONAR-PS subversion repository is located at:

https://svn.internet2.edu/svn/perfSONAR-PS 

Questions and comments can be directed to the author, or the mailing list. Bugs, feature requests, and improvements can be directed here:

https://bugs.internet2.edu/jira/browse/PSPS

VERSION

$Id$

AUTHOR

Jason Zurawski, zurawski@internet2.edu

LICENSE

You should have received a copy of the Internet2 Intellectual Property Framework along with this software. If not, see <http://www.internet2.edu/membership/ip.html>

COPYRIGHT

Copyright (c) 2004-2007, Internet2 and the University of Delaware

All rights reserved.

cpanm perfSONAR_PS::DB::RRD

perl -MCPAN -e shell
install perfSONAR_PS::DB::RRD