Each Telemetry Streams instance, when specified as part of a Telemetry Chart, must be associated with a Y-Axis. The syntax of a Telemetry Y-Axis is as follows:

y-axis <YAxisName> <ParameterList> = { <Label>, <NumberType>, <LowerBound>, <UpperBound>} ;

<YAxisName> 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 <YAxisName> is "PercentageChurnYAxis". <YAxisName>s are case-sensitive. While not required, ending each Y-Axis name with "YAxis" helps maintain uniqueness in the global namespace.

<ParameterList> is a possibly empty list of comma-separated identifiers defining the parameters for this Y-Axis instance. Parameters allow the calling entity for a Y-Axis (typically a Telemetry Chart) to dynamically specify some components of the y-axis definition.

<Label> is a string that will be used as the label for the Y-Axis. It should normally include a specification of the units associated with the values in the Streams associated with this Y-Axis. For example, "SLOC/hour", or "Active Time (minutes)".

<NumberType> is optional, and if supplied must be either the string "integer" or the string "double". It indicates whether the numbers listed on the Y axis should have a fractional part ("double") or not ("integer"). It defaults to "double".

<LowerBound> is an optional number indicating the highest guaranteed lower value to be listed in the Y-Axis. For example, this can be used to force the Y-Axis to start at zero, even if the lowest value present in the Streams associated with this Y-Axis is 50. If there are values in the Streams that are lower than <LowerBound>, then the Y-Axis will adjust and display to display the lowest value. If no <LowerBound> is specified, then the chart mechanism will dynamically determine the lower bound based upon the lowest value appearing the associated Streams.

<UpperBound> is an optional number indicating the lowest guaranteed upper value to be listed in the Y-Axis. For example, this can be used to force the Y-Axis to include 100, even if the highest value present in the Streams associated with this Y-Axis is 75. If there are values in the Streams that are greater than <UpperBound>, then the Y-Axis will adjust and display to display the highest value. If no <UpperBound> is specified, then the chart mechanism will dynamically determine the upper bound based upon the highest value appearing the associated Streams. If you wish to explicitly specify an <UpperBound>, then you must also explicitly specify a <LowerBound>.

Here are four representative examples of Y-Axis definitions illustrating the syntactic variations. It also illustrates the recommended formatting conventions for y-axis definitions.

y-axis SlocYAxis() = {
  "SLOC"
};

y-axis IntegerYAxis(label) = {
  label, "integer" 
};

y-axis ZeroYAxis(label) = {
  label, "integer", 0
};

y-axis PercentageYAxis(label, numberType) = {
  label, numberType, 0, 100
};

The first example, SlocYAxis, shows the minimal Y-Axis definition, in which just the label is specified. The system will default the NumberType to "double", and dynamically choose lower and upper bounds based upon the data values present in the associated Telemetry Streams. The second example, "IntegerYAxis", shows the use of a parameter which can be provided with a String when the Y-Axis is included in a Chart definition. The NumberType in this case is specified as "integer". The third and fourth examples show the specification of the lower and lower/upper bound values, respectively.

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.14, “ Definition Management Page portion with Y-Axis definitions ” illustrates a portion of the this page with chart definitions.

Figure 5.14.  Definition Management Page portion with Y-Axis definitions

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

Figure 5.15.  New Telemetry Y-Axis Definition

This screen image shows the "template" Y-Axis definition that appears to help you produce a syntactically correct Y-Axis definition. It also requires you to specify the visibility of the Y-Axis 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.