At the top level, the telemetry configuration file consists of two basic entities: Telemetry chart definitions, and Scene collection definitions.
Internally, the telemetry control center relies on the telemetry expert analysis interface on the Hackystat server to generate telemetry charts. In order to do so, it has to send telemetry chart definition in http request. Telemetry charts, along with the telemetry streams and y-axises they are dependent on, are defined in "TelemetryDefinition" element.
Example 6.1. Telemetry Definition
<TelemetryDefinition>
<![CDATA[
streams ActiveTime() = {"Active Time Telemetry Stream", ActiveTime()};
y-axis ActiveTimeAxis() = {"Hours", "double"};
chart ActiveTimeChart() = {"Active Time", (ActiveTime(), ActiveTimeAxis()) };
]]>
</TelemetryDefinition>
In Example 6.1, “Telemetry Definition”, a telemetry chart called "ActiveTimeChart" is defined, along with the dependent "streams" and "y-axis" constructs. Note that the actual telemetry definitions appear inside the CDATA section.
Multiple "TelemetryDefinition" elements can appear in the configuration file. Any number of "streams", "y-axis", and "chart" constructs can appear inside the CDATA section. The order they appear is not important. At the start time, the telemetry control center concatenates everything into a long string, and invokes the telemetry language parser. This implies that all definitions inside the configuration file share one single name space. Therefore, it's illegal to define two telemetry constructs of the same type with the same name. In case there is any error, the telemetry control center prints out the error message and quits immediately.
Note, however, the telemetry control center can only perform syntactical validity check. It won't know if you are using telemetry reducers or telemetry functions that are not supported by the Hackystat server. Such error would manifest itself only when the telemetry control center sends telemetry analysis request to the Hackystat sever, and receives an error message in response.
The telemetry control center displays telemetry charts scene by scene. Multiple charts form a scene, and multiple scenes form a scene group. A scene group does not affect the way telemetry charts are displayed. The sole purpose of a scene group is to organize relevant scenes together under the "Scene" menu on the control window.
Example 6.2. Telemetry Definition
<SceneCollection host="http://hackystat.ics.hawaii.edu/hackystat" userKey="your-user-key"
projectName="Hackystat-7" intervalType="Week" intervalSize="7" >
<Scene name="Issue Tracking" displayDuration="120">
<Chart chartName="ReleasePlan_IssueTrackingChart" templateValues="7.3"
displayTitle="Hackystat Release 7.3 Issue Tracking" />
</Scene>
</SceneCollection>
The description of the attributes used can be found in Table 6.2, “Description of Attributes”. Most attributes can be applied to "SceneCollection", "Scene", and "Chart" elements. In case of duplication, the attribute value in the inner element overrides the attribute value in the outer element, with the only exception of "name" attribute.
Table 6.2. Description of Attributes
| Attribute | Description |
|---|---|
| name | The name of "SceneCollection", "Scene", or "Chart". The value is used by the telemetry control center to provide visual clue to the user about the telemetry chart being displayed. It does not affect telemetry analysis on the Hackystat side, and thus does not affect the charts retrieved. |
| host | The url to the Hackystat server. |
| userKey | The Hackystat account key of the user whom the telemetry control center impersonates to send telemetry analysis requests. |
| projectName | The name of the project for which telemetry chart is retrieved. Note that the definition of the project must have already been defined on the Hackystat server. |
| chartName | The name of the telemetry chart defined in "TelemetryDefinition" section in the same configuration file. |
| templateValues | The value of the telemetry chart parameters. Note that this is a comma separated list. If the telemetry chart definition does not use any parameter, you can either supply an empty string or simply omit this attribute. |
| intervalType | One of "Day", "Week", or "Month". |
| intervalSize | The number of days, weeks, or months going back from today the requested telemetry chart should cover. |
| intervalString | If you know how the Hackystat telemetry analysis url is constructed, you can use this attribute to specify "intervalType" and "intervalSize" directly. It offers more flexibility, but is only recommended for expert users. |
| displayTitle | A string displayed above the telemetry chart. Note that the value is only used on the telemetry control center client side. |
| displayDuration | The time in seconds a scene should be displayed in automatic mode before cycling to the next scene. This attribute is only applicable to "Scene" and "SceneGroup" elements. |
| saveFileName | This attribute is only effective when you use the telemetry control center in batch mode to save retrieved telemetry charts on disk. It specified the name of the file (without extension) a chart should be saved. The extension is added automatically according to the chart type specified. Note that it is only applicable to "Chart" element. The this value is not supplied, then an internally generated file file is used when saving telemetry charts. |
Example 6.3, “A Telemetry Configuration File” illustrates a portion of a sample TCC configuration file.
Example 6.3. A Telemetry Configuration File
<?xml version="1.0" encoding="UTF-8"?>
<TelemetryViewer>
<TelemetryDefinition name="Commonly Used Y-Axis">
<![CDATA[
y-axis yAxis(label) = {label, "integer"};
y-axis doubleYAxis(label) = {label, "double"};
y-axis percentageYAxis(label) = {label, "integer", 0, 100};
]]>
</TelemetryDefinition>
<TelemetryDefinition>
<![CDATA[
streams ReleasePlan_TotalIssue(fixVersion, type, priority, memberEmail, filePattern)
= {"desc", Issue(fixVersion, type, "*", priority, memberEmail, filePattern) };
streams ReleasePlan_RemainingIssue(fixVersion, type, priority, memberEmail, filePattern)
= {"desc",
Issue(fixVersion, type, "Open", priority, memberEmail, filePattern)
+ Issue(fixVersion, type, "Reopened", priority, memberEmail, filePattern)
+ Issue(fixVersion, type, "In Progress", priority, memberEmail, filePattern)
};
chart ReleasePlan_IssueTrackingChart(fixVersion)
= {"Project Management - Remaining Issues v.s. Total Scheduled Issues",
(ReleasePlan_TotalIssue(fixVersion, "*", "*", "*", "**"), percentageYAxis("Issues")),
(ReleasePlan_RemainingIssue(fixVersion, "*", "*", "*", "**"), percentageYAxis("Issues"))
};
]]>
</TelemetryDefinition>
<TelemetryDefinition>
<![CDATA[
streams ReleasePlan_ClosedIssue(fixVersion, type, priority, memberEmail, filePattern)
= {"desc",
Issue(fixVersion, type, "*", priority, memberEmail, filePattern)
- Issue(fixVersion, type, "Open", priority, memberEmail, filePattern)
- Issue(fixVersion, type, "Reopened", priority, memberEmail, filePattern)
- Issue(fixVersion, type, "In Progress", priority, memberEmail, filePattern)
};
streams ReleasePlan_ClosedIssue2(fixVersion, type, priority, memberEmail, filePattern)
= {"desc",
Issue(fixVersion, type, "Closed", priority, memberEmail, filePattern)
+ Issue(fixVersion, type, "Resolved", priority, memberEmail, filePattern)
};
streams ReleasePlan_ActiveTime(filePattern, cumulative)
= {"desc", ActiveTime(filePattern, cumulative) };
chart ReleasePlan_IssueClosureAndActiveTimeChart(fixVersion)
= {"Project Management - Closed Issues and Team Active Times",
(ReleasePlan_ClosedIssue(fixVersion, "*", "*", "*", "**"), percentageYAxis("Issues")),
(ReleasePlan_ActiveTime("**", "true"), yAxis("Active Time Hours"))
};
]]>
</TelemetryDefinition>
<SceneCollection name="Issue Tracking"
host="http://hackystat.ics.hawaii.edu/hackystat"
userKey="your-user-key"
intervalType="Week"
intervalSize="7"
displayDuration="120"
projectName="Hackystat-7">
<Scene name="Release Cycle Issue Tracking">
<Chart chartName="ReleasePlan_IssueTrackingChart" templateValues="7.3"
displayTitle="Release 7.3 Total Issue and Remaining Issue"
intervalString="IntervalType=Week&WeekInterval.StartWeek=15-Jan-2006 to 21-Jan-2006&WeekInterval.EndWeek=12-Mar-2006 to 18-Mar-2006"
saveFileName="../../historical/total-and-remaining-issue-7.3"/>
<Chart chartName="ReleasePlan_IssueClosureAndActiveTimeChart" templateValues="7.3"
displayTitle="Release 7.3 Issue Closure and Team Active Time"
intervalString="IntervalType=Week&WeekInterval.StartWeek=15-Jan-2006 to 21-Jan-2006&WeekInterval.EndWeek=12-Mar-2006 to 18-Mar-2006"
saveFileName="../../historical/issue-closure-and-active-time-7.3"/>
<Chart chartName="ReleasePlan_IssueTrackingChart" templateValues="7.4"
displayTitle="Release 7.4 Total Issue and Remaining Issue"
projectName="Hackystat-7-740"
saveFileName="../../realtime/total-and-remaining-issue-7.4"/>
<Chart chartName="ReleasePlan_IssueClosureAndActiveTimeChart" templateValues="7.4"
displayTitle="Release 7.4 Issue Closure and Team Active Time"
projectName="Hackystat-7-740"
saveFileName="../../realtime/issue-closure-and-active-time-7.4"/>
</Scene>
</SceneCollection>
</TelemetryViewer>
A larger sample configuration file can be downloaded here if you are accessing this page from an installed Hackystat server. (The link will not work from the documentation on the Hackystat Developer Services web page.)
Note that for privacy reasons, the "userKey" attribute value is removed. To try the sample configuration file, you will need to provide your own Hackystat user key. You may also want to modify the "host" attribute to point it to your own Hackystat server.