To define a new Telemetry Chart instance, you supply a Telemetry Chart definition with the following syntax:

chart <ChartName> <ParameterList> = { <ChartTitle>, (<StreamExpression>, <YAxis>)+ } ;

<ChartName> is an identifier conforming to general Java syntax for identifier names (no embedded whitespace, weird characters, etc.) Also, the telemetry infrastructure maintains a global namespace for Streams, Charts, Y-Axes, and Reports, so the identifier chosen must be unique across the entire server. An example of a legal <ChartName> is "ActiveTimeChart". <ChartName>s are case-sensitive. While not required, ending each Chart name with "Chart" helps maintain uniqueness in the global namespace.

<ParameterList> is a possibly empty list of comma-separated identifiers defining the parameters for this Chart instance. Parameters allow the calling entity for a Chart (typically a Telemetry Report) to pass in a value to be provided to the internal Telemetry Streams instance(s).

<ChartTitle> is a string that will be displayed as the title of this chart.

Following the <ChartTitle> is a comma-separated list of one or more (<StreamExpression>, <YAxis>) pairs. The <StreamExpression> is a Telemetry Stream Expression, and <YAxis> is the specification of the Y-Axis that should be associated with the telemetry data produced by that <StreamExpression>.

	Sharing the Y-Axis among multiple Stream Expressions
	If the same Y-Axis instance is associated with more than one Stream Expression, then those Stream Expressions will all share the same Y axis when the chart appears. An example of this appears in the next section.

Here are four examples of Telemetry Chart definitions illustrating some of the syntactic variations. The example also includes the Y-Axis and Streams definitions used in the Chart definitions.

y-axis SimpleYAxis(label) = { 
  label 
};

streams ActiveTime(filePattern, cumulative) = {
  "Active Time",
  ActiveTime(filePattern, cumulative)
};

chart ActiveTimeChart() = { 
  "Cumulative Total Active Time",
  (ActiveTime("**", "true"), SimpleYAxis("Active Time (Hours)")) 
};

chart TotalAndJavaActiveTimeChart() = { 
  "Cumulative total and Java-specific Active Time",
  (ActiveTime("**", "true"), SimpleYAxis("Active Time (Hours)")),
  (ActiveTime("**/*.java", "true"), SimpleYAxis("Active Time (Hours)")) 
};

chart MultiAxisTotalAndJavaActiveTimeChart() = { 
  "Cumulative total and Java-specific Active Time",
  (ActiveTime("**", "true"), SimpleYAxis("Total Active Time (Hours)")),
  (ActiveTime("**/*.java", "true"), SimpleYAxis("Java Active Time (Hours)")) 
};

chart FlexibleActiveTimeChart(filePattern, cumulative) = { 
  "Cumulative or non-cumulative Active Time for the passed filePattern.", 
  (ActiveTime(filePattern, cumulative), SimpleYAxis("Active Time (Hours)"))
};

The first example, ActiveTimeChart, illustrates a very basic chart definition which displays the cumulative Active Time for a given Project and time interval.

The second example, TotalAndJavaActiveTimeChart, shows the total cumulative Active Time for all files in the Project, as well as the cumulative Active Time for just the Java source code files. Since the Y-Axis definition used in both cases is the same, only one Y axis will be produced for this chart.

The third example, MultiAxisTotalAndJavaActiveTimeChart, is almost the same as the second example, except that the two Y-Axis definitions are different (the label strings are not identical). Because of this, the chart will be generated with two Y axes. It is an interesting exercise to display information with combined and separated Y axes in this way; the two approaches yield very different visualizations of the information.

The final example, FlexibleActiveTimeChart, illustrates a chart definition with parameters.

As with Telemetry Streams and Y-Axes, the Definition Management command on the Preferences page allows you to display, edit, and define new Telemetry Charts. Figure 5.16, “ Definition Management Page portion with Charts ” illustrates a portion of this page with some chart definitions.

Figure 5.16.  Definition Management Page portion with Charts

This page displays all of the Telemetry Charts to which you have access. If you are the owner of a Chart, then you can edit or delete it. Another button enables you to define a new Chart. The page that appears is illustrated in Figure 5.17, “ New Telemetry Chart Definition ”.

Figure 5.17.  New Telemetry Chart Definition

This screen image shows the "template" Chart definition that appears to help you produce a syntactically correct definition. It also requires you to specify the visibility of the Chart definition. You can specify any of the Projects you own to make this definition visible to everyone in that Project, or "Global" to make this definition visible to all Hackystat users, or "Not Shared" to make this definition visible only to you.

Once you have defined a Telemetry Chart using the Telemetry Management command, the name of this Chart will now appear in the Telemetry Chart Analysis command. This allows you to generate this Telemetry Chart for a specific Project and Time Interval, as illustrated in Figure 5.18, “ Invoked Telemetry Chart ”.

Figure 5.18.  Invoked Telemetry Chart

Because this Chart was defined with two parameters, we must specify them as part of the invocation in the "Parameter Values" field. In this case, we specify a filePattern that limits the code churn computation to Java code, and "true" for the cumulative parameter, indicating that we want the stream to show the aggregation of churn values over time.

The Telemetry Management command allows you to define Telemetry Charts in terms of predefined Telemetry Streams. Once you've done that, you can then view the results by invoking the Telemetry Chart Analysis. This is a good approach when (a) you understand what telemetry data you want to visualize in a Chart, (b) there is already a predefined Telemetry Stream appropriate to your needs, and (c) you want to save the resulting Chart definition for later use or for sharing with other users.

However, what if you aren't exactly sure what Reduction Functions to incorporate into a Telemetry Stream for further incorporation into a Telemetry Chart and subsequent display with an actual Project and Time Interval? In this case, it is quite tedious to iteratively edit Telemetry Stream and Chart definitions using the Telemetry Management interface followed by the use of the Telemetry Chart command to display the results. When you're not exactly sure what you want, the Telemetry Expert Analysis command provides an interactive Stream, Chart, and Report definition facility that speeds up the exploration of telemetry data and its visualization.

For example, let's look at how we could interactively generate a Chart containing cumulative active time using the Telemetry Expert Analysis command. This is illustrated in Figure 5.19, “ Interactive Chart Definition using the Telemetry Expert Analysis ”.

Figure 5.19.  Interactive Chart Definition using the Telemetry Expert Analysis

As we saw in Figure 5.13, “ Telemetry Streams Visualization ”, the Telemetry Expert Analysis enables you to type in telemetry definitions and then use the "draw" construct to display them. In the above example, we must first define a Y-Axis and a Streams instance, then construct the Chart instance using those definitions. We then invoke the "draw" command to generate the graph corresponding to the Chart instance. So that all of the definitions would appear in the text box, the normal formatting standards for Telemetry Definitions were not employed and each definition appears on a single line.

What makes the Telemetry Expert Analysis command so useful is the ability to quickly edit your definitions and rerun the results over the same Project and Time Interval. For example, having generated the Chart showing the total cumulative Active Time on this Project over this Interval, let's say that we want to see the non-cumulative Active Time for comparative purposes. All we do is change the "true" to "false", press the Analyze button, and we get the new Chart, as illustrated in Figure 5.20, “ Interactive Chart Modification ”.

Figure 5.20.  Interactive Chart Modification

For more information on the Telemetry Expert Interface, see Section 5.4.5, “Exploring Streams Definitions with the Telemetry Expert Analysis command”. Let's now turn to the final Telemetry Language construct that allows us to combine together Charts into a Report.