This is documentation for the next version of Grafana. For the latest stable release, go to the latest version.
Introduction to histograms and heatmaps
A histogram is a graphical representation of the distribution of numerical data. It groups values into buckets (sometimes also called bins) and then counts how many values fall into each bucket.
Instead of graphing the actual values, histograms graph the buckets. Each bar represents a bucket, and the bar height represents the frequency (such as count) of values that fell into that bucket’s interval.
This histogram shows the value distribution of a couple of time series. You can easily see that most values land between 240-300 with a peak between 260-280.
Histograms only look at value distributions over a specific time range. The problem with histograms is you cannot see any trends or changes in the distribution over time. This is where heatmaps become useful.
A heatmap is like a histogram, but over time where each time slice represents its own histogram. Instead of using bar height as a representation of frequency, it uses cells and colors the cell proportional to the number of values in the bucket.
In this example, you can clearly see what values are more common and how they trend over time.
There are a number of data sources supporting histogram over time like Elasticsearch (by using a Histogram bucket aggregation) or Prometheus (with histogram metric type and Format as option set to Heatmap). But generally, any data source could be used if it meets the requirements: returns series with names representing bucket bound or returns series sorted by the bound in ascending order.
Raw data vs aggregated
If you use the heatmap with regular time series data (not pre-bucketed), then it’s important to keep in mind that your data is often already aggregated by your time series backend. Most time series queries do not return raw sample data but include a group by time interval or maxDataPoints limit coupled with an aggregation function (usually average).
This all depends on the time range of your query of course. But the important point is to know that the histogram bucketing that Grafana performs might be done on already aggregated and averaged data. To get more accurate heatmaps it is better to do the bucketing during metric collection or store the data in Elasticsearch, or in the other data source which supports doing histogram bucketing on the raw data.
If you remove or lower the group by time (or raise maxDataPoints) in your query to return more data points your heatmap will be more accurate but this can also be very CPU and memory taxing for your browser and could cause hangs and crashes if the number of data points becomes unreasonably large.
Related Grafana resources
GrafanaCONline 2021 is coming June 7-17
Be the first to learn about exciting next-generation features in Grafana 8.0, be inspired by what community members are building, and attend expert-led sessions and workshops on Grafana, Prometheus, Loki logs, and more.
All about Grafana plugins: Visualizing disparate data sources in one place
Grafana Enterprise plugins are integrations with other commercial monitoring tools (such as Datadog, Splunk, New Relic, ServiceNow, Oracle, and Dynatrace) that are created, maintained, and supported by the Grafana Labs team.
Demo: Getting started with Grafana Enterprise and observability
Join the Grafana Labs team for a 30-minute demo of how to get started with the Grafana Stack, so you can go from zero to observability in just a few minutes.