This document describes how you can create and interpret a chart that displaysmetric data of theDistribution value type.This value type is used by services when the individual measurements are toonumerous to collect, but statistical information, such as averages orpercentiles, about those measurements is valuable.For example, when an application relies on HTTP traffic, you can use adistribution-valued metric that captures HTTP response latency to evaluatehow quickly HTTP requests complete.

To illustrate how a histogram is created, consider a service that measuresthe HTTP latency of requests and that reports this data by using a metric witha distribution-value type. The data is reported every minute.The service defines ranges of values for the metric, calledbuckets, andrecords the count of measured values that falls into each bucket.For example, when an HTTP request completes, the service increments the countin the bucket whose range includes the request's latency value. These countscreate a histogram of values for that minute.

Assume that the latencies measured in a one-minute interval are5, 1, 3, 5, 6, 10, and 14. If the buckets are [0, 4), [4, 8), [8, 12), and[12, 16), then the histogram of this data is [2, 3, 1, 1].The following table showshow individual measurements affect the count for each bucket:

Bucket	Latency measurements	Number of values in the bucket
[12,16)	14	1
[8,12)	10	1
[4,8)	5, 5, 6	3
[0,4)	1, 3	2

When this data is written to the time series, aPointobject is created. For metrics with a distribution value, that objectincludes the histogram of values. For this sampling period, thePoint contains [2, 3, 1, 1]. The individual measurements aren'twritten to the time series.

Assume that the previous table records the histogram for the latency data asmeasured at time 1:00. That table illustrates how to take a series ofmeasurements and convert them into bucket counts. Suppose that the bucketcounts at times 1:01, 1:02, and 1:03 are as shown in the following table:

Bucket	Histogram for 1:00	Histogram for 1:01	Histogram for 1:02	Histogram for 1:03
[12,16)	1	6	0	1
[8,12)	1	0	2	2
[4,8)	3	1	1	8
[0,4)	2	6	10	3

The previous table displays a sequence of histograms indexed by time. Eachcolumn in the table represents the latency data for a one-minute period. To getthe number of measurements at a specific time, sum the bucket counts. However,the actual measurements aren't shown as those measurements aren't availablein distribution-valued metrics.

Heatmap charts

Heatmap charts are designed to display a single time series with distributionvalues. For these charts, theX-axis represents time, theY-axis representsthe buckets, and color represents the value. The brighter the colorindicates a higher value. For example, dark areas of the heatmap indicatelower bucket counts than yellow or white areas.

The following figure is one representation of a heatmap for the previousexample:

In the previous figure, the heatmap uses black to represent the smallestbucket count, 0, and yellow to represent the largest bucket count, 10. Redsand oranges represent values between these two extremes.

Because heatmap charts can display only a single time series, you must set theaggregation options to combine all time series.

To use Metrics Explorer to display the sum of theRTT latencies of a VM instance, do the following:

1. In the Google Cloud console, go to theleaderboard Metrics explorer page:

   Go toMetrics explorer

   If you use the search bar to find this page, then select the result whose subheading isMonitoring.

2. In the toolbar of the Google Cloud console, select your Google Cloud project. ForApp Hub configurations, select the App Hub host project or the app-enabled folder's management project.
3. In theMetric element, expand theSelect a metric menu, enterRTT latencies in the filter bar, and then use the submenus to select a specific resource type and metric:
   1. In theActive resources menu, selectVM Instance.
   2. In theActive metric categories menu, selectVm_flow.
   3. In theActive metrics menu, selectRTT latencies.
   4. ClickApply.

4. To add filters, which remove time series from the query results, use theFilter element.

Line and bar charts

Line charts, stacked bar charts, and stacked line charts, which are designed todisplay scalar data, can't displaydistribution values. To display a metric with a distribution valuewith one of these chart types,you must convert the histogram values into scalar values.For example, you can set the aggregation options to compute the mean of thevalues in the histogram or to compute a percentile.

For information about how to display a distribution-valued metric ona line chart, see the following section.

Aggregation and distribution metrics

Aggregation is the process of regularizing points within atime series and of combining multiple time series. Aggregation is the same fordistribution type metrics as it is for metrics that have a value typeof integer or double. However, the chart type enforces some requirements on thechoices used for aligning and grouping time series.

Heatmap charts

Heatmap charts display one distribution-valued time series. Therefore, thealignment function andgrouping functionmust be set to create a single time series.

Select asum ordelta alignment function when a chart displays a heatmap.These functions combine, at the bucket level, all samples for asingle time series that are in the same alignment period, and the result is adistribution value. For example, if two adjacent samples of atime series are [2, 3, 1, 1] and [2, 5, 4, 1], then the sum alignmentfunction produces [4, 8, 5, 2].

The grouping function defines how different time series arecombined. This function is sometimes called an aggregator or a reducer.For heatmaps, set the grouping function to thesum function.The sum function adds the values of the same buckets across all histograms,resulting in a new histogram. For example, thesum of the value [2, 3, 1, 1] from timeseries-A and the value[1, 5, 2, 2] from timeseries-B is [3, 8, 3, 3].

Line charts

Line charts display only scalar-valued time series. If you select adistribution-valued metric, then the chart is configured with optimalparameters to display a heat map. The fields of theAggregation elementare set toDistribution andNone.

• The interpretation ofDistribution depends on the specific metric.For distribution-valued metric types that have aGAUGE metric kind,the default alignment function is set tosum. When a distribution-valuedmetric type has aCUMULATIVE metric kind, the default alignmentfunction isDELTA.

• The setting ofNone ensures that all time times are combined.

If you want to display a distribution-valued metric on a line chart,then you must change the default settings of your chart.For example, to configure a line chart on a dashboard to display the 99thpercentile of every time series for a distribution-valued metric,do the following:

1. In the Google Cloud console, go to thedashboard Dashboards page:

   Go toDashboards

   If you use the search bar to find this page, then select the result whose subheading isMonitoring.

2. In the toolbar of the Google Cloud console,select your Google Cloud project. ForApp Hubconfigurations, select the App Hub host project or management project.
3. In the toolbar, clickadd Add widget.
4. In theAdd widget dialog, selectleaderboard Metric.
5. In theMetric element, and select theVM Instance - RTT latencies metric.
6. In theAggregation element, expand the first menu and select99th percentile.
7. In theDisplay pane, set the value of theWidget type menu toLine chart.
8. Optional: In theAggregation element, expand the second menu and selectthe labels used to group time series. By default, no labels are selected,and therefore one line is displayed on the chart.

What's next

For information about how to determine the bucket model for a metric andhow to interpret percentiles, seePercentiles and distribution-valued metrics.