Source: http://www.apdex.org/index.php/2010/08/apdex-g-section-5-reporting/
Timestamp: 2019-04-18 10:34:11+00:00

Document:
I’m writing a series of posts about Generalizing Apdex. This is #19. To minimize confusion, section numbers in the current spec are accompanied by the section symbol, like this: §1. The corresponding section numbers in the generalized spec, Apdex-G, are enclosed in square brackets, like this: .
I have been working systematically through the process of generalizing the current Apdex spec. Along the way, I have been skipping over parts of the current spec to work on the paragraphs that presented challenges. I am now going back to fill in those less contentious paragraphs, posting updated drafts of each section of the Apdex-G spec. The first four are Section  Introduction, Section  Index Overview, Section  Calculation Inputs, and Section  Calculating the Index; today I continue with Section  Reporting.
The introduction is a rewording of the current spec.
Section [5.1] corresponds to Apdex section §5.1. I have numbered the four rules.
Section [5.1.1] corresponds to Apdex section §5.3, describing general cases. Placing it here improves the flow.
Section [5.2] corresponds to the last part of Apdex section §5.1 on Uniform Output, revised and extended. These extensions were discussed in two previous posts — Configurable Reporting in Apdex-G and Report Groups and Quality Ratings in Apdex-G.
Section [5.3] corresponds to Apdex section §5.2. I have generalized the language, and tried to enumerate the possible classes of errors in a general way. This section was discussed briefly with the first draft.
Section [5.4] corresponds to Apdex section §5.4. I have generalized the language.
The index is a decimal value between 0 and 1. The Apdex representation on all reports (screen, print, or otherwise) must adhere to the following rules.
In this section, the terms Report(s) and Reporting refer to any representation of an Apdex index, whether in print, on a computer screen, or elsewhere.
The index always starts with a 0, followed by a decimal point, followed by the fractional value for the calculation to two decimals, and the value of T is clearly associated with the index presentation as defined below. There is a special case of the value 1.00 that starts with the digit of 1. A 1.00 is presented when the formula produces a result that can be rounded arithmetically to 1.00 (results equal to or greater than 0.995 round to 1.00).
Apdex may not be reported in granularity smaller than one one-hundredth. Decimal values of 3 or more digits are not permitted.
Tools in a computer screen or in printed reports always identify it as an Apdex value. When there are many values of the index presented in tabular form representing many reporting groups, then the Apdex label should appear with the appropriate column or row.
All Apdex values are calculated with a particular target threshold, T. The value of T must be clearly displayed in association with the Apdex score. Furthermore, in order to facilitate exporting Apdex values from a tool and then importing them to other analysis tools, all tools must support at least one uniform output as shown below.
The index is a decimal value between 0 and 1, rounded to a precision of two decimal places. Values equal to or greater than 0.995 round to 1.00.
Unless its value is 1.00, the index is always reported with a zero in the tens place, followed by a decimal point, followed by no more than two decimal places.
Apdex values must be identified as such. When several Apdex values are presented in tabular form, a single Apdex identifier can be identify a group of values in a row, column, or table.
All Apdex values are calculated based on specified performance zones. The performance zone specification must be clearly displayed in association with the Apdex score.
General Apdex value discussions that reflect any target of T are written with “T” as shown in the following examples.
In general discussions of Apdex values, references to unspecified performance thresholds are written using the notation “[T]”, as shown in the following examples.
Sections [5.3] and [5.4] also use this notation when referring to threshold reporting.
The tool shall display, print, and export to an ASCII file each Apdex value with the following fixed format.
Examples of the uniform output are: 0.85 [5.5], 1.00 [8.0]*, 0.90 [4.0], and 0.77 .
Tools may display Apdex values with a T shown as a mathematical subscript. For example, an Apdex value of 0.75 that is based upon a T of 4 seconds is shown as 0.754.
When T has a decimal component, as defined in section 3.3, then the exact value of T must be shown (example: 0.754.5). In order to make the index easy to read, tools may drop the decimal portion of T if it is zero (example: 0.754.0 becomes 0.754).
Separate tools may be used to calculate Apdex index values from measurement data and to report Apdex index values. To support the exchange of index values between Apdex analysis and reporting tools, all Apdex analysis tools must support the Apdex Uniform Output format. A tool shall display, print, and export Apdex-G values to an ASCII file having a comma-separated values (CSV) format. For this purpose, Apdex-G incorporates the IETF specification of CSV published in RFC 4180 (see section  References).
A Uniform Output File is composed of a uniform output header record, followed by one or more uniform output data records. The header record contains the same number of comma-separated fields as all data records in the file. Fields in the header record contain fixed literal values, or names that correspond to each field in the data records. The content of a uniform output header and data records are described in Tables 2 and 3 below. In Table 2, each element except the last is followed by a comma.
Note 1: To avoid ambiguity, tool creators must ensure that Report Group description fields do not contain commas, because commas separate fields in the Uniform Output format.
If a tool has obtained user-specified names for performance intervals, those names should be included in the corresponding fields of the header record (elements 21, 23, and 25 in Table 2). If user-specified names are not available, distinct default names must be supplied for each performance interval field in the header record. See also section [2.5.1] Thresholds and Performance Intervals.
In Table 2, each Interval Group (elements 21, 23, and 25) is composed of one or more Performance Interval elements, separated by commas. Table 3 shows the structure of a single Performance Interval element, therefore the components shown in Table 3 are not separated by commas.
Note 2: Interval Notation, described in References [6.8], uses a comma to separate the upper and lower bounds of an interval. To avoid ambiguity Apdex substitutes a colon, because commas separate fields in the Uniform Output format.
The Uniform Output File format comprises three sections, each having its own identifier (fields 2, 11, and 18). The Report Group Metadata Section and the Apdex Index Section are required, because they contain the necessary data for reporting Apdex scores. The Input Data Summary Section is optional, but tool creators are encouraged to produce this data at the analysis stage, and to pass it to Reporting tools. Reporting tools can use this data to provide additional context for Apdex scores. If the Input Data Summary Section is omitted, fields 11 through 17 must be omitted from the header and data records.
Apdex values are calculated based upon a set of measurements (samples) in the report group. If there are a small number of samples, the tool must still present a result. However, a result for such a small report group must be clearly marked.
When an Apdex value is the output of a small group (1 to 99) calculation, an asterisk (*) must be appended to that value. Examples: 0.80 [4.0]*, 0.804*.
The Apdex calculation could not be performed because there were no samples (NS) within the report group. Where the calculated Apdex value would normally appear, the tool will show an output of NS [T], where [T] is the normal threshold display (see section [5.1.1]).
When an Apdex value is the output of a small group calculation, an asterisk (*) must be appended to that value, for example: 0.84* [T], where [T] is the normal threshold display (see section [5.1.1]).
Some tool vendors may wish to add graphical aids to report the Apdex value. This is an optional feature, but, if implemented, it must follow these guidelines.
Two forms of alternative representations are permitted: the rating (a word), and a color indication. The following table shows the fixed set of alternative modes of representing the Apdex. The table shows examples where the target threshold (T) is 4 seconds.
The color indication can be determined by the vendor in line with their existing product set, however a legend must clearly indicate which color represents each Apdex rating.
Note. In the current specification, the ‘Apdex Value Range’ column of Table 3 contains a typo in the ‘NoSample’ row, which (as shown above) reads ‘0.NS4‘. That cell should read ‘NS4‘.
Some tool creators may wish to assign quality ratings to Apdex value ranges, and to present those ratings graphically. This is an optional feature, but, if implemented, it must follow these guidelines.
Two alternative representations are permitted for quality ratings: a rating word or a color indication. Table 6 below lists the value ranges to be used when assigning a rating to an Apdex value. The table shows examples for the target threshold [T], where [T] is the normal threshold display as described in section [5.1.1].
Colors may be selected by the vendor for consistency with other products, or based on user-supplied preferences. However a legend must clearly indicate which color represents each Apdex rating.
Note: An addendum may specify alternative colors [TBD: and/or value ranges?] to be applied when reporting Apdex scores for a particular measurement domain.
I added Notes 1,2 to Tables 2,3 addressing the need to avoid using commas within the fields of a CSV format file.

References: §1
 §5
 §5
 §5
 §5
 §5