1.0 Introduction

One very important kind of information collected by Hackystat is called "Sensor Data". As its name implies, this is data that is collected by "sensors", which are small software plugins attached to tools in the development environment.

All sensor data instances are required to provide six required fields: timestamp, runtime, sensordatatype, resource, owner and tool.

In addition, sensor data instances can provide any number of optional fields which provide domain-specific information. For example, a sensor attached to an editor might want to provide information about the type of editing event that triggered the sensor. A sensor attached to a code complexity tool might want to provide information about complexity values, and so forth.

For higher level analyses to operate efficiently and effectively, they must have some way of quickly determining which sensor data instances are relevant to them, as well as some expectation about the nature of the optional fields available. In the same way, sensors for tools with similar purposes should use the same optional fields in the same way so that analyses can interoperate.

To enable an analysis to quickly find data of relevance, Hackystat provides the "sensordatatype" field. When a sensor generates a sensor data instance with a particular string for the sensordatatype, it is indicating that this instance will contain a certain set of optional properties.

In prior versions of Hackystat, the set of domain-specific fields were declaratively specified and could be checked automatically at run time. During the design of Version 8, we decided that our prior approach created burdensome levels of coupling between components, and it also made evolution of structure quite difficult to manage. We decided with Version 8 to adopt a "convention over configuration" approach to sensor data type specification. While the required fields would still be enforced by the system, the set of sensor data types, and the optional fields associated with them, would be managed informally.

The purpose of this document is to provide a reference for the current set of "standard" sensor data types and their "standard" optional fields. This document does not prevent someone from creating sensors that gather information with a new sensor data type field and with new optional fields that they operate on with new nalyses of their own creation.

2.0 Sensor Data Structure

Sensor Data is represented in XML. For example:

<?xml version="1.0"?>
<SensorData>
 <Timestamp>2007-04-30T09:00:00.000-10:00</Timestamp>
 <Runtime>2007-04-30T09:00:00.000-10:00</Runtime>
 <Tool>Subversion</Tool>
 <SensorDataType>Commit</SensorDataType>
 <Resource>file://home/johnson/svn/Foo/build.xml</Resource>
 <Owner>http://dasha.ics.hawaii.edu:9876/sensorbase/user/hongbing@hawaii.edu</Owner>
 <Properties>
   <Property>
     <Key>TotalLines</Key>
     <Value>137</Value>
   </Property>
   <Property>
     <Key>LinesAdded</Key>
     <Value>10</Value>
   </Property>
   <Property>
     <Key>LinesDeleted</Key>
     <Value>12</Value>
   </Property>
   <Property>
     <Key>Repository</Key>
     <Value>svn://www.hackystat.org/</Value>
   </Property>
   <Property>
     <Key>RevisionNumber</Key>
     <Value>2345</Value>
   </Property>
   <Property>
     <Key>Author</Key>
     <Value>johnson</Value>
   </Property>
  </Properties>
</SensorData>

What you can see immediately is that a SensorData instance is comprised of seven interior elements: Timestamp, Runtime, SensorDataType, Resource, Owner, and Properties. The first six elements constitute "required fields" that every SensorData instance contains. The seventh element, Properties, contains a list of key-value pairs that provides type-specific information.

Sensor Data is transmitted and received using RESTful principles. See Sensor Data REST API for details.

You can, of course, generate and send this XML using the language of your choice. If you happen to be using Java, we have developed two libraries that can be helpful:

• SensorBaseClient (JavaDoc, Examples) provides useful facilities for sensor data retrieval, and basic facilities for transmission.
• SensorShell (JavaDoc, UserGuide) provides more sophisticated facilities for sensor data transmission.

3.0 Required Sensor Data Fields

Every sensor data instance contains the following required fields:

4.0 Standard Sensor Data Types

4.1 Sensor data type descriptions

The following table lists the current set of "standard" sensor data types.

4.2 Domain-specific sensor data fields

The following table lists, for each sensor data type, the set of optional fields (properties) that sensor instances of a given type typically provide.

5.0 Defining a new sensor data type

If you wish to define a new sensor data type, it is best to come up with a set of key-value pairs that you believe represent the data adequately, then submit it to the hackystat developers list for review. This helps guarantee that your proposed representation will work as well as possible with higher level services such as DailyProjectData.