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 )