NAME

perfSONAR_PS::DB::PingER -A module that provides base Rose::DB implementation of data access for PingER databases

DESCRIPTION

This module provides access to the relevant Rose::DB methods given the relevant contact points for the database. It also provides some transparency to the numerous data tables that is used by PingER in order to provide performance.

SYNOPSIS

  # create a new database object but calling the Rose::DB register db function
  # note that this allows more than one database to be defined, however
  # we will only use the default/default one.
  perfSONAR_PS::DB::PingER->register_db(
    domain      => 'default',
    type        => 'default',
    driver      => $db_driver,
    database => $db_name,
    host        => $host,
    port        => $port,
    username    => $username,
    password    => $password,
  );
        
  # try to open the db
  my $db = perfSONAR_PS::DB::PingER->new_or_cached();
 
  # open the database
  if ( $db->openDB() == 0 ) {
        
        # There are two ways of getting at the data, either use the wrapper classes
        # or use the Rose::DB::Objects directly.
        
        # get the appropiate rose::db::object that represents a host; this will
        # automatically insert the entries into the host table if it does not exist
        my $src = $db->get_host( 'localhost', '127.0.0.1' );
        my $dst = $db->get_host( 'iepm-resp.slac.stanford.edu', '134.79.240.36' );

        # setup some values for the metadata entry
        my $transport = 'ICMP';
        my $packetSize = '1008';
        my $count = 10;
        my $packetInterval = 1;
        my $ttl = '64';
        
        # get the rose::db::object for the metadata, again, this will automatically
        # insert the entry into the database if it does not exist
        my $metadata = $db->get_metadata( $src, $dst, $transport, $packetSize, $count, $packetInterval, $ttl );
        
        # say we have the data we want to insert as a hash
        $hash = {
                                'timestamp' => '1000000000', # REQUIRED
                                'minRtt'        => '0.023',
                                'maxRtt'        => '0.030',
                                'meanRtt'       => '0.026',
                                'minIpd'        => '0.0',
                                'maxIpd'        => '0.002',
                                'meanIpd'       => '0.006',
                                'iqrIpd'        => '0.0001',
                                'lossPercent'   => '0.0',
                                'outOfOrder'    => 'true',                                                                      
                                'duplicates'    => 'false',     
        }'
        
        # now, given that we have the metadata, insert some data into database
        my $data = $db->insert_data( $metadata, $hash );
        
  } else 
        print "Something went wrong with the database init.";
  }
  

error( $ )

accessor/mutator for the last error message

openDB

opens a connection to the database, creating the rose db object loaders necessary to instantiate the in-memory objects for further query of the tables directly

Returns 0 = if everything is okay -1 = somethign went wrong

closeDB

closes the connection to the database

soi_host( $ip_name, $ip_number )

'select or insert host': wrapper method to look for the table host for the row with ip_name $ip_name and ip_number $ip_number' and return the appropiate Rose::DB::Object for the host table entry.

get_metadata( $src, $dst, $transport, $packetSize, $count, $packetInterval, $ttl )

wrapper method to retrieve the relevant rose::db:object of the metadata entry given rose::db::objects of the source $src to destination $dst using a hash of key/value pairs: $hash ={ 'transport' = # ICMP, TCP, UDP 'packetSize' = # packet size of pings in bytes 'count' = # number of packets sent 'packetInterval' = # inter packet time in seconds 'ttl' = # time to live of packets

}

insert_data( $metadata, $hash );

inserts into the database the information presented with the rose::db::metadata object $metadata (also the output of get_metadata()) with the information presented in the hash $hash. $hash should contain $hash = {

        # REQUIRED values
        'timestamp' => # epoch seconds timestamp of test

        # RTT values
        'minRtt'        => # minimum rtt of ping measurement
        'meanRtt'       => # mean rtt of ping measurement
        'maxRtt'        => # maximum rtt of ping measurement
        
        # IPD
        'minIpd'        => # minimum ipd of ping measurement
        'meanIpd'       => # mean ipd of ping measurement
        'maxIpd'        => # maximum ipd of ping measurement
        
        # LOSS
        'lossPercent' => # percentage of packets lost
        'clp'           => # conditional loss probability of measurement
        
        # JITTER
        'iqrIpd'        => # interquartile range of ipd value of measurement
        'medianRtt'     => # median value of rtts
        
        # OTHER
        'outOfOrder'    => # boolean value of whether any packets arrived out of order
        'duplicates'    => # boolean value of whether any duplicate packets were recvd.

        # LOG
        'rtts'          => [] # array of rtt values of the measurement
        'seqNums'       => [] # array of the order in which sequence numbers are recvd
}

Returns 0 = everything okay -1 = somethign went wrong

}

get_table_for_timestamp( $ )

from the provided timestamp (in epoch seconds), determines the names of the rose::db object and manager classes required for the data tables used in PingER. Will automatically include (use) the relevant modules.

the final argument 'createNewTables' defines a boolean for whether tables within the timetange should be created or not if it does not exist in the database.

If a second argument is provided, will assume that a time range is given and will load all necessary tables;

Returns ( rose data table array of strings, rose data manager array of string )