This document assumes familiarity with the concepts introduced in how-to-write-metrics.
Metrics produce Histograms, which are serialized into an HTML file named results.html by default. Upon opening this HTML file in Chrome, after all of the Histograms are loaded, the histogram-set-table processes them and displays many names, numbers, and controls.
This complex UI can be overwhelming initially, but understanding how to use it can pay off in deep performance insights.
We'll skip the top two rows of controls for now because they modify what information is displayed in the table, which we need to understand first.
The first column always contains Names. Usually, these are Histogram names, which are the strings that metrics pass to Histogram constructors. However, as we'll see in “The Groupby-picker”, if you group by attributes of Histograms besides their name, like the “story name”, then this first Name column will contain the name of the grouping of Histograms, such as the story name.
The other columns contain Histogram values. One of the other attributes of Histograms is their displayLabel. If these Histograms were produced by Telemetry, then you can pass --results-label to Telemetry's run_benchmark command to set a label for all of the Histograms produced by that benchmark run. Otherwise, displayLabel will default to the benchmark name plus the time that the benchmark was run. There is a separate value column for each distinct displayLabel value, which is displayed in the header cell.
Histograms can be grouped into a tree configured by the groupby-picker, described below. Non-leaf node Histograms are merged from the Histograms that are grouped under them. Histograms that are grouped together are only mergeable if they share the same units and bin boundaries.
If a non-leaf node Histogram is merged from unmergeable Histograms, then the table will display that non-leaf node Histogram as the string “(unmergeable)”.
Click the up/down pointing triangles in the table header row in order to sort the table by that column. Sorting the Name column sorts alphabetically. Sorting Value columns sorts numerically by Histogram average.
Click a blue line chart icon in the Name column to display the overview line charts in that row. These line charts graph Histogram averages. The x-axes of these charts differ:
The x-axis of the overview line chart in the Name column corresponds to the value columns.
The x-axis of the overview line chart in the Value columns correspond to the Histograms in the Grouping Tree that were merged to produce the Histogram in that table cell.
By default, table cells contain only averages of the Histograms in those cells.
Click the bar chart icon in table cells to display more information about the Histogram:
Metadata may contain
Metrics can add diagnostics either to samples within Histograms or to Histograms themselves.
Click and drag the mouse around the bar chart in order to display sample diagnostics for the selected Histogram bins.
Sample diagnostics may include Breakdown diagnostics, which indicate relative sizes of component metrics for the selected samples.
When the name of and entries in a Breakdown diagnostic align with a RelatedNameMap diagnostic on the parent Histogram, the table rows become clickable links to the related Histograms. For more about summation metrics, see Diagnostic Metrics.
The groupby-picker sits just above the table and allows you to control how Histograms are grouped into the Grouping Tree.
Grouping keys include
You can enable or disable grouping keys by clicking the checkboxes, and re-order them by clicking the left and right arrows.
Finally, the row of controls at the top of the screen contains several different small control elements. Let's start at the left.
Type a regex in the Search box to filter Histograms out of the displayed HistogramSet whose name do not match the regex.
For example, the v8 metric produces Histograms whose names end with either “duration” or “count”. The “duration” Histograms cannot be merged with the “count” histograms. If you group by any other grouping key besides “name” first, then the table will try to merge some “count” Histograms with some “duration” Histograms. The two different kinds of Histograms have different units, so they cannot be merged, so the table will display “(unmergeable)”. In order to make the table ignore the “count” Histograms so that it can merge all of the “duration” Histograms together, you can filter out the “count” Histograms by entering “duration” in the Search box.
Toggle the Overview Line Charts for all visible rows at once by clicking the blue line chart button to the right of the Search box.
