Background
PerfSONAR allows transparent access to numerous network-based metrics/characteristics such as latency, throughput and availability. Similarily IEPM-BW has been gathering and presenting such network data for the last few years.
However, whilst the PerfSONAR framework defines a flexible and extendable method for metric retrival and storage, IEPM-BW currently does not. More precisely, it is difficult to collect network measurement data from IEPM-BW databases in a form other than graphical.
PerfSONAR defines the use of the NMWG specification for the transport of network characteristics. In particular, they define the representation of these metrics as XML constructs that should enable all NMWG-enabled software to communicate.
A Measurement Archive is a database of network characteristics that is accessible to a PerfSONAR service. This database may currently be of type RRD or SQL. As IEPM-BW network data is currently stored in MySQL, it seems sensible to be able to front IEPM-BW network data through PerfSONAR by defining and implementing a IEPM-BW Measurement Archive for PerfSONAR.
Pre-requisites
It is of course necessary to have PerfSONAR working. It is also necessary to compile and install the SQL-MA for PerfSONAR (note not yet installed!).
Implementation
The following link is documentation of the steps required to implement new data into the SQL-MA: http://wiki.perfsonar.net/jra1-wiki/index.php/Adding_new_metrics_to_the_SQL_MA
iBatis Configuration
iBatis is a set of classes that enable the mapping of SQL data directly into code. This allows the flexible definition and separation of the relationships between a SQL statement and java code.
The configurations are defined in XML files that map the method call to that of teh SQL statement.
An example (taken from the CLMP OwAMP definitions) is:
<select id="getResults1"
parameterMap="select-parameters1" resultMap="select-results">
<![CDATA[
select receiveSynchronized, receiveTime, receiveTimeError, sendSynchronized, sendTime, send
TimeError, seqNum, timeType, timeValue, ttl
from clmp_owamp
where metadataId = ?
and timeValue >= ?
and timeValue <= ?
order by timeValue ASC
]]>
</select>
which specifies a method call getResults1 which takes a parameter list defined in a (unshown) XML definition that specifies the required input parameters select-parameters1; and it gives out results in a (unshown) XML definition select-results.
This loose coupling of code to SQL implementations means that it should be relatively trivial to map IEPM-BW MySQL tables and results for PerfSONAR.
eXist Configuration
In order to map the method calls to PerfSONAR (meta) data, the eXist definitions have to be configured. The following example shows the default Utilisation definitions for the SQL-MA.
<nmwg:metadata id="meta1-test">
<netutil:subject id="subj1">
<nmwgt:interface>
<nmwgt:hostName>test-hostName</nmwgt:hostName>
<nmwgt:ifAddress type="ipv4">10.1.2.3</nmwgt:ifAddress>
<nmwgt:ifName>test-0</nmwgt:ifName>
<nmwgt:ifDescription>test description</nmwgt:ifDescription>
<nmwgt:direction>in</nmwgt:direction>
<nmwgt:authRealm>TestRealm</nmwgt:authRealm>
<nmwgt:capacity>1000BaseT</nmwgt:capacity>
</nmwgt:interface>
</netutil:subject>
<nmwg:parameters>
<nmwg:parameter name="supportedEventType">utilization</nmwg:parameter>
</nmwg:parameters>
</nmwg:metadata>
<nmwg:data id="data1-test" metadataIdRef="meta1-test">
<nmwg:key>
<nmwg:parameters>
<nmwg:parameter name="metadataId">meta1-test</nmwg:parameter>
<nmwg:parameter name="ibatisConfig">ibatis-SqlMapConfig-utilization.xml</nmwg:param
eter>
</nmwg:parameters>
</nmwg:key>
</nmwg:data>
The metadata data1-test defines the use of the metadataId 'meta1-test' from which an ibatis mapping file ibatis-SqlMapConfig-utilization.xml is defined:
<resultMap id="select-results" class="java.util.HashMap">
<result property="value" column="value" />
<result property="timeValue" column="timeValue" />
<result property="valueUnits" column="valueUnits" />
</resultMap>
<parameterMap id="select-parameters1" class="java.util.HashMap">
<parameter property="metadataId" />
<parameter property="startTime" />
<parameter property="endTime" />
</parameterMap>
<select id="getResults1"
parameterMap="select-parameters1" resultMap="select-results">
<![CDATA[
select value, timeValue, valueUnits
from perfsonar_utilization
where metadataId = ?
and timeValue >= ?
and timeValue <= ?
order by timeValue ASC
]]>
</select>
Two mapping's are defined which are used in input and output parameters for the method call getResults1. select-results defines taht the properties are mapped to columns in the table definition for this utilisation data. (another file defines the location and accesss requirements of the SQL database).
Java Implementation
In order to map the input from PerfSONAR to these iBatis mappings, it is necessary to write some code that extends some of the SQL-MA framework so that new metrics can be implemented. They are:
org.perfsonar.service.measurementArchive.metadataConfig.queryGenerator.MetadataQueryGenerator
Based upon a supplied NMWG spec. input Message, this class constructs the necessary XQuery statement.
org.perfsonar.service.measurementArchive.sqlType.fetch.ResponseGenerator
This maps the supplied data from the SQL (through iBatis) to the required NMWGv2 spec as defined in the class org.ggf.ns.nmwg.base.v2_0.Data.
(There is also a store class that should be implemented - however, we do no consider this functionality as this time).
Add Class Definitions to the SQL-MA Service
Finally, the classes writen above need to be linked into the SQL-MA by editing a XML file conf/eventType-map.xml. An example for the default Utilisation spec is shown:
<eventType>
<name>utilization</name>
<metadataQueryGenerator>org.perfsonar.service.measurementArchive.metadataConfig.queryGenerator.UtilizationQueryGenerator</metadataQueryGenerator>
<responseGenerator>org.perfsonar.service.measurementArchive.sqlType.fetch.UtilizationResponseGenerator</responseGenerator>
<storeRequestProcess>org.perfsonar.service.measurementArchive.sqlType.store.UtilizationStoreRequestProcess</storeRequestProcess>
</eventType>