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

report <ReportName> <ParameterList> = { <ReportTitle>, <ChartExpression>+ } ;

<ReportName> 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, Reports, Y-Axes, and Reports, so the identifier chosen must be unique across the entire server. An example of a legal <ReportName> is "ActiveTimeReport". <ReportName>s are case-sensitive. While not required, ending each Report name with "Report" helps maintain uniqueness in the global namespace.

<ParameterList> is a possibly empty list of comma-separated identifiers defining the parameters for this Report instance. Parameters allow the calling entity for a Report (typically a user) to pass in one or more values to be provided to the internal Telemetry Chart instance(s). Note that we recommend that Reports be defined with an empty parameter list to facilitate their use by novice users.

<ReportTitle> is a string that will be displayed as the title of this report.

<ChartExpression> indicates an invocation of a Telemetry Chart. Multiple invocations can be defined in a comma-separated list.

Here is an example of a Telemetry Report definition.

report JavaFileSizeAndTimeReport() = { 
  "Java File Size and Time", 
  JavaFileMetric-Sloc("**"), 
  ActiveTime("**/*.java", "true")
};

This example, JavaFileSizeAndTimeReport, illustrates a simple report consisting of two Charts. Note that it does not make much sense to define a Report consisting of one Chart: you might as well simply display the Chart by itself.

As with Telemetry Streams, Y-Axes, and Charts, the Definition Management command on the Preferences page allows you to display, edit, and define new Telemetry Reports. Figure 5.21, “ Telemetry Definition Management Page showing Reports ” illustrates a portion of the Definition Management page containing some sample Report definitions.

Figure 5.21.  Telemetry Definition Management Page showing Reports

This page displays all of the Telemetry Reports to which you have access. If you are the owner of a Report, then you can edit or delete it. Another button enables you to define a new Report, as illustrated in Figure 5.22, “ New Telemetry Report Definition ”.

Figure 5.22.  New Telemetry Report Definition

This screen image shows the "template" Report definition that appears to help you produce a syntactically correct definition. It also requires you to specify the visibility of the Report 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 Report using the Telemetry Definition Management command, the name of this Report will now appear in the Telemetry Report Analysis command. This allows you to generate this Telemetry Report for a specific Project and Time Interval, as illustrated in Figure 5.23, “ Invoked Telemetry Report ”.

Figure 5.23.  Invoked Telemetry Report

To conserve space, this screen image shows only two of the three Charts generated by the HackystatActiveTimeAndSize report. The report reveals two of the many possible relationships between size and time. For the hackyKernel module during the selected time interval, Active Time and Size in SLOC co-vary quite closely. However, for the hackyTelemetry module, size drops quite precipitously during the time interval, perhaps as a result of refactoring.

Finally, note that this telemetry report was defined to take no parameters. As we discussed previously, we find it helpful to new users to define Telemetry Reports that do not take any parameters. This minimizes their need to understand the details of the telemetry language in order to generate reports.

The Telemetry Management command allows you to define Telemetry Reports in terms of predefined Telemetry Charts. As discussed previously, this is fine when you know what Charts you want to combine. If you want to experiment with combining different Charts together, then Telemetry Expert Analysis command provides an easy way to do that.

Figure 5.24, “ Interactive Report Definition using the Telemetry Expert Analysis ” illustrates a report definition.

Figure 5.24.  Interactive Report Definition using the Telemetry Expert Analysis

As we saw in Figure 5.13, “ Telemetry Streams Visualization ” and Figure 5.19, “ Interactive Chart Definition using the Telemetry Expert Analysis ” 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 define a Y-Axis, a Streams, and a Chart before finally defining the Report instance we are interested in. Following that, we can use the Draw command to display the resulting Report. So that all of the definitions could be displayed within the text box, the Report definition is overly simple, consisting of just a single Chart invocation. In normal cases, Report instances consist of a comma-separated sequence of Chart invocations.