Heatmap Panel

The Heatmap Panel displays a data series as a histogram over time. Rather than simply plotting the raw value of a metric in a graph and seeing how the value changes over time, a heatmap allows you to sort each data point into different buckets based on its value, and visualize the frequency or how often a particular value occurs and how that frequency changes over time.

Compared to Histograms

When using the Graph Panel, you can set its X-axis Mode to Histogram. With this setting, each value in the data series will be sorted into different buckets together with other data points that have a similar value. The resulting panel will display the range of values (buckets) on the X-axis, and the number of data points in each bucket along the Y-axis.

For example, consider a device that measures the water level of a river. The raw data can be plotted in a regular graph to see the height of the water at a particular time. However, due to daily tidal behavior, intermittent weather, and long-term seasonality, it may be difficult to identify trends by just looking at the raw data itself.

With a histogram, the water height data is organized into (for example) "low," "normal," and "high" buckets, allowing you to quickly visualize the number of times the water level was measured at each level. In this trivial example, you might expect the water level to be "low" 25% of the time, "normal" 50% of the time, and "high" 25% of the time. As your device collects more data, the histogram may begin to shift as rainfall results in more instances where the water level is measured as "high."

The limitation of a histogram is that it is a single representation of the distribution of all data points in a given time range, and therefore it is difficult to visualize how the distribution has changed over time. With a heatmap, the data is first divided into time buckets (such as 1-day, 1-week, 1-month, or other time interval), and then the low/normal/high distribution is calculated for each interval.

When using a heatmap, the time intervals are arranged on the X-axis, and the distribution is plotted on the Y-axis. Finally, rather than changing the "height" of each bucket to indicate the number of data points in the bucket, the color of the bucket is adjusted. This allows you to quickly understand the distribution of data points in a single time interval, and how that distribution changes over time.

Creating a Heatmap Panel

  1. Click the Add panel button at the top of the dashboard.

  2. From the list of available panels, select Heatmap.

    The heatmap panel will be added to your dashboard.


    Heatmap panel

Editing Panel Settings

To edit the heatmap panel settings, click the Panel Title, then select Edit.


The General tab lets you configure basic panel settings. Refer to the Lagoon Panels: General documentation for more information.


The Metrics tab lets you configure the data series source. Refer to the Lagoon Panels: Metrics documentation for more information.


The Axes tab lets you configure the heatmap area and buckets.


Heatmap panel axes options

Y Axis


Data format


The Display tab lets you configure the look and feel of the heatmap.


Heatmap panel display options


Color scale




Time Range

The Time Range tab lets you adjust the range of data to use. Refer to the Lagoon Panels: Time Range documentation for more information.

Additional Resources

More information about the heatmap panel can be found in the Grafana: Heatmap Panel documentation.