frequencyHisto([<timeWindow>,] [<bucketName>,] <tsExpression> [,metrics|sources|sourceTags|pointTags|<pointTagKey>] )
Converts a histogram coming from Google Cloud Platform, Telegraf, or any other source to Wavefront histogram format. Users can then manipulate the histogram with Wavefront histogram query functions.
|timeWindow||Amount of time in the moving time window. You can specify a time measurement based on the clock or calendar (1s, 1m, 1h, 1d, 1w), the window length (1vw) of the chart, or the bucket size (1bw) of the chart. Defaults to 1m.|
|bucketName||Optional string that describes the bucket. Default is lt, that is, less than. If your source histogram uses a different tag key to specify the buckets, specify that tag key here.|
|tsExpression||Ordinary histogram distribution that we'll convert to a Wavefront histogram.|
|metrics|sources|sourceTags|pointTags|<pointTagKey>||Optional 'group by' parameter for organizing the time series into subgroups and then returning each histogram subgroup. Use one or more parameters to group by metric names, source names, source tag names, point tag names, values for a particular point tag key, or any combination of these items. Specify point tag keys by name.|
This function converts ordinary histogram data to Wavefront histograms. Histogram data is defined as a set of time series where each series represents the frequency of outcomes in a particular bucket, bounded by a tag such as
One use case is to visualize GCP distributions, which can be ingested into Wavefront using the Google Cloud Platform Integration. Distribution bucket data is ingested as
gcp.<metric>.bucket with an
lt tag defining the upper bound of each bucket. You can use
frequencyHisto(ts(gcp.<metric>.bucket)) to convert the bucket data to a Wavefront histogram.
When a chart displays the result of this function, it shows the median by default. You can use
percentile() to change that and, for example, show the 90% percentile.
The function generates a histogram by creating a T-digest and adding sampling points based on the range and the count of the bucket.
Similar to aggregation functions for metrics,
frequencyHisto() returns a single distribution per specified time window. To get separate distributions for groups that share common characteristics, you can include a ‘group by’ parameter, as for many ts() queries. For example, use
frequencyHisto(<expression>, sources) to group by sources.
The function returns a separate series of results for each group.
frequencyHisto() function itself doesn’t perform interpolation because that doesn’t make sense for a histogram. But when you apply
percentile(), we do perform interpolation.
The following example shows how to visualize a Google Cloud Platform distribution in Wavefront. Let’s say that we have used the GCP Metrics Explorer to find the 95th percentile of a distribution, grouped by
Now let’s do the same in Wavefront. The GCP integration ingests the distribution’s bucket data, so we can use
ts() to visualize the bucket data.
Then we use
frequencyHisto() to convert the data to a Wavefront histogram and group by
location, and finally, we use
percentile() to find the 95th percentile of the histogram.
- Our histogram doc page gives background information about Wavefront histograms.
cumulativeHisto()function is similar but converts Prometheus cumulative histograms to Wavefront ordinary histograms.
This function is meant for original histograms, like those that come from Google Cloud Platform. It’s not useful for cumulative histogram distributions like those coming from Prometheus.