NAME
perfSONAR_PS::Services::MA::perfSONARBUOY - A module that provides methods for the perfSONARBUOY MA. perfSONARBUOY exposes data formerly collected by the AMI framework, including BWCTL and OWAMP data. This data is stored in a database backend (commonly MySQL). The webservices interface provided by this MA currently exposes only iperf data collected via BWCTL.
DESCRIPTION
This module, in conjunction with other parts of the perfSONAR-PS framework, handles specific messages from interested actors in search of BWCTL/OWAMP data. There are three major message types that this service can act upon:
- MetadataKeyRequest - Given some metadata about a specific measurement,
request a re-playable 'key' to faster access
underlying data.
- SetupDataRequest - Given either metadata or a key regarding a specific
measurement, retrieve data values.
- MetadataStorageRequest - Store data into the archive (unsupported)The module is capable of dealing with several characteristic and tool based eventTypes related to the underlying data as well as the aforementioned message types.
init($self, $handler)
Called at startup by the daemon when this particular module is loaded into the perfSONAR-PS deployment. Checks the configuration file for the necessary items and fills in others when needed. Initializes the backed metadata storage (DBXML or a simple XML file) and builds the internal 'key hash' for the MetadataKey exchanges. Finally the message handler loads the appropriate message types and eventTypes for this module. Any other 'pre-startup' tasks should be placed in this function.
Due to performance issues, the database access must be handled in two different ways:
- File Database - it is expensive to continuously open the file and store it as
a DOM for each access. Therefore it is opened once by the
daemon and used by each connection. A $self object can
be used for this.
- XMLDB - File handles are opened and closed for each connection.createStorage($self { metadatadb } )
Given the information in the AMI databases, construct appropriate metadata structures into either a file or the XMLDB. This allows us to maintain the query mechanisms as defined by the other services. Also performs the steps necessary for building the 'key' cache that will speed up access to the data by providing a fast handle that points directly to a key.
prepareDatabases($self, { doc })
Opens the XMLDB and returns the handle if there was not an error. The optional argument can be used to pass an error message to the given message and return this in response to a request.
needLS($self {})
This particular service (perfSONARBUOY MA) should register with a lookup service. This function simply returns the value set in the configuration file (either yes or no, depending on user preference) to let other parts of the framework know if LS registration is required.
registerLS($self $sleep_time)
Given the service information (specified in configuration) and the contents of our metadata database, we can contact the specified LS and register ourselves. We then sleep for some amount of time and do it again.
handleMessageBegin($self, { ret_message, messageId, messageType, msgParams, request, retMessageType, retMessageNamespaces })
Stub function that is currently unused. Will be used to interact with the daemon's message handler.
handleMessageEnd($self, { ret_message, messageId })
Stub function that is currently unused. Will be used to interact with the daemon's message handler.
handleEvent($self, { output, messageId, messageType, messageParameters, eventType, subject, filterChain, data, rawRequest, doOutputMetadata })
Current workaround to the daemon's message handler. All messages that enter will be routed based on the message type. The appropriate solution to this problem is to route on eventType and message type and will be implemented in future releases.
maMetadataKeyRequest($self, { output, metadata, time_settings, filters, request, message_parameters })
Main handler of MetadataKeyRequest messages. Based on contents (i.e. was a key sent in the request, or not) this will route to one of two functions:
- metadataKeyRetrieveKey - Handles all requests that enter with a
key present.
- metadataKeyRetrieveMetadataData - Handles all other requestsThe goal of this message type is to return a pointer (i.e. a 'key') to the data so that the more expensive operation of XPath searching the database is avoided with a simple hashed key lookup. The key currently can be replayed repeatedly currently because it is not time sensitive.
metadataKeyRetrieveKey($self, { metadatadb, key, metadata, filters, request_namespaces, output })
Because the request entered with a key, we must handle it in this particular function. We first attempt to extract the 'maKey' hash and check for validity. An invalid or missing key will trigger an error instantly. If the key is found we see if any chaining needs to be done (and appropriately 'cook' the key), then return the response.
metadataKeyRetrieveMetadataData($self, $metadatadb, $metadata, $chain, $id, $request_namespaces, $output)
Similar to 'metadataKeyRetrieveKey' we are looking to return a valid key. The input will be partially or fully specified metadata. If this matches something in the database we will return a key matching the description (in the form of an MD5 fingerprint). If this metadata was a part of a chain the chaining will be resolved and used to augment (i.e. 'cook') the key.
maSetupDataRequest($self, $output, $md, $request, $message_parameters)
Main handler of SetupDataRequest messages. Based on contents (i.e. was a key sent in the request, or not) this will route to one of two functions:
- setupDataRetrieveKey - Handles all requests that enter with a
key present.
- setupDataRetrieveMetadataData - Handles all other requestsChaining operations are handled internally, although chaining will eventually be moved to the overall message handler as it is an important operation that all services will need.
The goal of this message type is to return actual data, so after the metadata section is resolved the appropriate data handler will be called to interact with the database of choice (i.e. mysql, sqlite, others?).
setupDataRetrieveKey($self, $metadatadb, $metadata, $chain, $id, $message_parameters, $request_namespaces, $output)
Because the request entered with a key, we must handle it in this particular function. We first attempt to extract the 'maKey' hash and check for validity. An invalid or missing key will trigger an error instantly. If the key is found we see if any chaining needs to be done. We finally call the handle data function, passing along the useful pieces of information from the metadata database to locate and interact with the backend storage (i.e. rrdtool, mysql, sqlite).
setupDataRetrieveMetadataData($self, $metadatadb, $metadata, $id, $message_parameters, $output)
Similar to 'setupDataRetrieveKey' we are looking to return data. The input will be partially or fully specified metadata. If this matches something in the database we will return a data matching the description. If this metadata was a part of a chain the chaining will be resolved passed along to the data handling function.
handleData($self, $id, $data, $output, $et, $message_parameters)
Directs the data retrieval operations based on a value found in the metadata database's representation of the key (i.e. storage 'type'). Current offerings only interact with rrd files and sql databases.
retrieveSQL($self, $d, $mid, $output, $et, $message_parameters)
Given some 'startup' knowledge such as the name of the database and any credentials to connect with it, we start a connection and query the database for given values. These values are prepared into XML response content and return in the response message.
addSelectParameters($self, { parameter_block, filters })
Re-construct the parameters block.
SEE ALSO
Log::Log4perl, Module::Load, Digest::MD5, English, Params::Validate, Sys::Hostname, Fcntl, Date::Manip, Math::BigInt, perfSONAR_PS::OWP, perfSONAR_PS::OWP::Utils, perfSONAR_PS::Services::MA::General, perfSONAR_PS::Common, perfSONAR_PS::Messages, perfSONAR_PS::Client::LS::Remote, perfSONAR_PS::Error_compat, perfSONAR_PS::DB::File, perfSONAR_PS::DB::SQL
To join the 'perfSONAR-PS' mailing list, please visit:
https://mail.internet2.edu/wws/info/i2-perfsonarThe perfSONAR-PS subversion repository is located at:
https://svn.internet2.edu/svn/perfSONAR-PSQuestions 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/PSPSVERSION
$Id: perfSONARBUOY.pm 1856 2008-03-18 17:03:46Z zurawski $
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.