NAME

perfSONAR_PS::DB::RRD - A module that provides a simple API for dealing with data stored in rrd files through the RRDTool's 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 that is present in the other DB modules of perfSONAR_PS.

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

Create a new RRD object. All arguments are optional:

 * path - path to RRD executable on the host system
 * name - name of the RRD file this object will be reading
 * dss - hash reference of datasource values
 * error - Flag to allow RRD to pass back error values

The arguments can be set (and re-set) via the appropriate function calls.

setFile($self, { file })

Sets the RRD filename for the RRD object.

setPath($self, { path })

Sets the 'path' to the RRD binary for the RRD object.

setVariables($self, { dss })

Sets several variables (as a hash reference) in the RRD object.

setVariable($self, { dss })

Sets a variable value in the RRD object.

setError($self, { error })

Sets the error variable for the RRD object.

getErrorMessage($self, { })

Gets any error returned from the underlying RRDp module for this RRD object.

openDB($self, { })

'Opens' (creates a pipe) to the defined RRD file.

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 enter into the commit phase (i.e. by calling the commit function). This allows us to stack up a bunch of values first, and reuse time figures.

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.

SYNOPSIS

    use perfSONAR_PS::DB::RRD;

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

    # or also:
    # 
    # my $rrd = new perfSONAR_PS::DB::RRD;
    # $rrd->setFile({ path => "/home/jason/rrd/stout/stout.rrd" });
    # $rrd->setPath({ file => "/usr/local/rrdtool/bin/rrdtool" });  
    # $rrd->setVariables({ dss => {'eth0-in'=>"" , 'eth0-out'=>"", 'eth1-in'=>"" , 'eth1-out'=>""} });  
    # $rrd->setVariable({ dss => "eth0-in" });
    # ...
    # $rrd->setError({ error => 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({
      cf => "AVERAGE", 
      resolution => "", 
      end => "1163525343", 
      start => "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({ time => "N", ds => "eth0-in", value => "1" });
    $rrd->insert({ time => "N", ds => "eth0-out", value => "2" });
    $rrd->insert({ time => "N", ds => "eth1-in", value => "3" });
    $rrd->insert({ time => "N", ds => "eth1-out", value => "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";
    }
    

SEE ALSO

RRDp, Log::Log4perl, Params::Validate, 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-2008, Internet2 and the University of Delaware

All rights reserved.

cpanm perfSONAR_PS::DB::RRD

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