Aaron Brown > perfSONAR_PS-Services-MA-SNMP-0.09 > perfSONAR_PS::Services::MA::SNMP

Download:
perfSONAR_PS-Services-MA-SNMP-0.09.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.09   Source  

NAME ^

perfSONAR_PS::Services::MA::SNMP - A module that provides methods for the perfSONAR-PS SNMP based Measurement Archive (MA).

DESCRIPTION ^

This module, in conjunction with other parts of the perfSONAR-PS framework, handles specific messages from interested actors in search of SNMP 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.

API ^

The offered API is not meant for external use as many of the functions are relied upon by internal aspects of the perfSONAR-PS framework.

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.

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.

loadXMLDB( { metadatadb } )

If the deployment has an existing store file, but would like to utilize an XML DB instance, this function will load the old data into an existing XML DB. This operation is non-destructive.

buildHashedKeys($self {})

With the backend storage known we can search through looking for key structures. Once we have these in hand each will be examined and Digest::MD5 will be utilized to create MD5 hex based fingerprints of each key. We then map these to the key ids in the metadata database for easy lookup.

needLS($self {})

This particular service (SNMP 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 requests

The 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 requests

Chaining 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. rrdtool, mysql, sqlite).

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.

retrieveRRD($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, Date::Manip, 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::RRD, perfSONAR_PS::DB::SQL

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: SNMP.pm 1877 2008-03-27 16:33:01Z aaron $

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.

syntax highlighting: