Metrics Results UI

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.

The Table

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 Name Column

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 first, left-most column is the Name column.

The Value Column(s)

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.

The other columns contain values splayed by label.

Grouping Tree

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.

Rows are grouped and nested to form a tree.

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)”.

Attempts to merge unmergeable Histograms display (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.

Columns are sortable.

The Overview Line Charts

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:

Overview Line Charts in the Name Column

The x-axis of the overview line chart in the Name column corresponds to the value columns.

Overview line chart comparing columns.

Overview Line Charts in 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.

Overview line chart comparing subrows.

The Show Histogram Button

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:

  • Histogram bin count bar chart (if the Histogram has only a single bin, then it will be a box chart),
  • summary statistics as configured by the metric,
  • Up to 3 groups of diagnostics may be available in tabs:
    • Metadata
    • Sample diagnostics
    • Other diagnostics added to Histograms by metrics

Diagnostics tabs

Metadata may contain

  • Information about the device that produced the results
  • Telemetry context
  • Source control revisions
  • Links to logs and traces These metadata diagnostics are added to Histograms by telemetry or other processes outside of metrics.

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.

Show full Histogram data for a cell.

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

The groupby-picker sits just above the table and allows you to control how Histograms are grouped into the Grouping Tree.

Grouping keys include

  • Histogram name
  • Benchmark name
  • Story name
  • Storyset repetition
  • Story repetition
  • Legacy TIR label for TBMv1 benchmarks
  • Story grouping keys

You can enable or disable grouping keys by clicking the checkboxes, and re-order them by clicking the left and right arrows.

The groupby-picker configures how Histograms are grouped.

The Top Controls

Finally, the row of controls at the top of the screen contains several different small control elements. Let's start at the left.

The Search box

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.

Filter Histograms by searching.

The Total Overview Chart Button

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.