NAME

perfSONAR_PS::Services::MA::Status - A module that provides methods for a an L2 Status Measurement Archive. The service can be used to make Link Status Data available to individuals via webservice interface.

DESCRIPTION

This module, in conjunction with other parts of the perfSONAR-PS framework, handles specific messages from interested actors in search of link status data.

There are two 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. - MeasurementArchiveStoreRequest - Given some metadata or a key and some link status information, updates status information about a given link.

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. 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.

needLS($self) This particular service (Status 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 backend database, we can contact the specified LS and register ourselves. The $sleep_time ref can be set to specify how long before the perfSONAR-PS daemon should call the function again.

handleEvent($self, { output, messageId, messageType, messageParameters, eventType, subject, filterChain, data, rawRequest, doOutputMetadata })

    This function is called by the daemon whenever there is a metadata/data
    pair for this instance to handle. This function calls the subject parsing
    routines that are common to all requests, then calls the filter chaining
    parsing routines which are common to all requests and then passes the
    results onto the specific function depending on the request.

parseSubject ($self, $subject_md) There are five possible subject types that are acceptable depending on the context: an nmwg key, a topoid subject, an nmwg subject with 'compat' subject information in it, an nmwg subject with the old style link IDs in them (deprecated) and an empty subject. This function calls the relevant parsing function depending on the content of the subject metadata.

parseKey ($self, $key) Parses the nmwg keys that we generate and hand off to the users.

parseCompatSubject ($self, $compat_subj) Stub function that throws an error for now. Will eventually parse the subjects in the form that the SQLMA expects.

lookupLinkIDs ($self, $topo_exp) Takes a topology id expression and matches it with the identifiers in the SQL backend.

resolveSelectChain ($self, $subject_md, $filterChain, $selectTime) This function takes the filter chain and tries to resolve it down to a single point in or range of time. It takes the subject metadata since some of the protocol options would take parameters from there, the filter chain itself and a $selectTime that is undef in all cases other than keys. In the case of a key, it may correspond to a specific time range and in that case, $selectTime will have a perfSONAR_PS::Time element with the time point/range for the key.

handleStoreRequest ($self, $output, $metadataId, $link_id, $responseType, $knowledge, $do_update, $data) This function handles a store request. It pulls the updated information to store from the data element, making sure that all the relevant data is there. After that, it updates the link state in the database and then adds a metadata/data pair to show that the store request was handled properly.

handleLinkStatusRequest ($self, $output, $metadataId, $linkIds, $time, $responseType, $was_key) This function handles a link status request. First, it checks whether the history of a link should be retrieved or the just the specified point/range, calling the appropriate function for each. Next, it must output the data. Key requests never have the specific link element output, just the key. Since the daemon will handle outputting the key for us, we can safely not output the metadata in that case. In all other cases, we must output the appropriate link information. Thus, we check whether the incoming request was a key, if so we do nothing, if not, we output the appropriate MD depending on the format of the incoming response. Once we've done that, we go through and output the resulting link status.

handleMetadataKeyRequest ($self, $output, $metadataId, $link_ids, $time, $responseType, $was_key) This function takes the relevant link ids and generates output containing the keys associated with those link ids. The function is almost identical to the handleLinkStatusRequest in its output. It just outputs the key for a link instead its associated data.

outputMetadata ($self, $output, $link_id, $parentMdId, $responseType) There are 3 different formats that the metadata in a response can take. The 'linkid' format is deprecated and kept around for existing software out there. However, there are two other formats available: topoid and compat. Topoid outputs a topoid subject containing the link identifier. Compat outputs in format compatible with the SQLMA.

outputLinkIDMetadata ($self, $output, $link_id, $parentMdId) Outputs a metadata containing the specified link id in the format expected by legacy pS-PS Status MA applications.

outputTopoIDMetadata ($self, $output, $link_id, $parentMdId) Outputs a metadata containing the specified link id in the new topoid format.

outputCompatMetadata ($self, $output, $link_id, $parentMdId) Outputs the metadata for the given link id in the format expected by applications compatible with the SQLMA L2 Status MA.

outputNodeElement ($self, $output, $node) Outputs a node element in the format expected by applications compatible with the SQLMA L2 Status MA

outputLinkElement ($self, $output, $link) Outputs a link element in the format expected by applications compatible with the SQLMA L2 Status MA

createKey ($self, $output, $link_id, $time, $responseType) Outputs a key with the relevant time, responseFormat and link id so that a client can simply return that key and get the information associated with it.

writeoutLinkState_range ($self, $link) Writes out the specified perfSONAR_PS::Status::Link element in a format backwards compatible with the ifevt standard. It adds four attributes to the standard ifevt datum: startTime, startTimeType, endTime and endTimeType. These added attributes give the range during which the link had the specified state.

writeoutLinkState_range ($self, $link) Writes out the specified perfSONAR_PS::Status::Link element in a format compatible with the ifevt standard.

parseLinkDefinitionsFile ($self, $file) Parses a file containing link definition information that is used for compatibility with the SQLMA L2 Status MA. The format of the file is similar to:

<config> <node name="node0"> <city>Bobville</city> <country>US/country <institution>Monkey House</institution> <latitude>0</latitude> <longitude>0</longitude> </node> <node name="node1"> <city>Bobville</city> <country>US/country <institution>Monkey House</institution> <latitude>0</latitude> <longitude>0</longitude> </node>

        <link knowledge="full">
                <globalName>SOME-LINK</globalName>
                <localName>SOME-LINK-LOCAL1</localName>
                <linkID>urn:ogf:network:domain=internet2.edu:host=149.165.129.17:port=1-A-1-1:link=1</linkID>
                <endpoint type="demarcpoint" name="node0" />
                <endpoint type="endpoint" name="node1" />
        </link>
</config>

SEE ALSO

perfSONAR_PS::Services::Base, perfSONAR_PS::Time, perfSONAR_PS::Client::LS::Remote, perfSONAR_PS::Client::Status::SQL, perfSONAR_PS::Topology::ID

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.

VERSION

$Id:$

AUTHOR

Aaron Brown, aaron@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::Services::MA::Status

perl -MCPAN -e shell
install perfSONAR_PS::Services::MA::Status