Heatmap

Heatmaps allow you to view histograms over time. While histograms display the data distribution that falls in a specific value range, heatmaps allow you to identify patterns in the histogram data distribution over time. For more information about heatmaps, refer to Introduction to histograms and heatmaps.

For example, if you want to understand the temperature changes for the past few years, you can use a heatmap visualization to identify trends in your data:

{{< figure src="/static/img/docs/heatmap-panel/temperature_heatmap.png" max-width="1025px" alt="A heatmap visualization showing the random walk distribution over time" >}}

{{< docs/play title="Grafana Heatmaps" url="https://play.grafana.org/d/heatmap-calculate-log/" >}}

You can use a heatmap visualization if you need to:

• Visualize a large density of your data distribution.
• Condense large amounts of data through various color schemes that are easier to interpret.
• Identify any outliers in your data distribution.
• Provide statistical analysis to see how values or trends change over time.

Configure a heatmap visualization

Once you’ve created a dashboard, the following video shows you how to configure a heatmap visualization:

{{< youtube id="SGWBzQ54koE" >}}

Supported data formats

Heatmaps support time series data.

Example

The table below is a simplified output of random walk distribution over time:

The data is converted as follows:

{{< figure src="/static/img/docs/heatmap-panel/heatmap.png" max-width="1025px" alt="A heatmap visualization showing the random walk distribution over time" >}}

Pan and zoom panel time range

{{< docs/shared lookup="visualizations/panel-pan-zoom.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Configuration options

{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Panel options

{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Heatmap options

The following options control how data in the heatmap is calculated and grouped.

Y-Axis options

The following options define the display of the y-axis.

{{< docs/shared lookup="visualizations/multiple-y-axes.md" source="grafana" version="<GRAFANA_VERSION>" leveloffset="+3" >}}

Colors options

The color spectrum controls the mapping between value count (in each bucket) and the color assigned to each bucket. The leftmost color on the spectrum represents the minimum count and the color on the right most side represents the maximum count. Some color schemes are automatically inverted when using the light theme.

You can also change the color mode to Opacity. In this case, the color will not change but the amount of opacity will change with the bucket count

Mode

Use the following options to define the heatmap colors.

• Scheme - Bucket value represented by cell color.
  • Scheme - If the mode is Scheme, then select a color scheme.
• Opacity - Bucket value represented by cell opacity. Opaque cell means maximum value.
  • Color - Cell base color.
  • Scale - Scale for mapping bucket values to the opacity.
    • Exponential - Power scale. Cell opacity calculated as value ^ k, where k is a configured Exponent value. If exponent is less than 1, you will get a logarithmic scale. If exponent is greater than 1, you will get an exponential scale. In case of 1, scale will be the same as linear.
      • Exponent - Value of the exponent, greater than 0.
    • Linear - Linear scale. Bucket value maps linearly to the opacity.

Steps

Set a value between 1 and 128.

Reverse

Toggle the switch to reverse the color scheme. This option only applies the Scheme color mode.

Start/end color scale from value

By default, Grafana calculates cell colors based on minimum and maximum bucket values. With Start color scale from value and End color scale at value, you can overwrite those values. Consider a bucket value as a z-axis, with the start and end values as z-min and z-max.

• Start color scale from value - Minimum value used for cell color calculation. The placeholder Auto (min) uses the series minimum value. If the bucket value is less than this value, then it's mapped to the minimum color.
• End color scale at value - Maximum value used for cell color calculation. The placeholder Auto (max) uses the series maximum value. If the bucket value is greater than this value, then it's mapped to the maximum color.

Cell display options

Use these settings to control the display of heatmap cells.

Tooltip options

Tooltip options control the information overlay that appears when you hover over data points in the visualization.

Tooltip mode

When you hover your cursor over the visualization, Grafana can display tooltips. Choose how tooltips behave.

• Single - The hover tooltip shows only a single series, the one that you are hovering over on the visualization.
• All - The hover tooltip shows all series in the visualization. Grafana highlights the series that you are hovering over in bold in the series list in the tooltip.
• Hidden - Do not display the tooltip when you interact with the visualization.

Use an override to hide individual series from the tooltip.

Show color scale

When you set the Tooltip mode to Single, this option is displayed. This option controls whether or not the tooltip includes the color scale that's also represented in the legend. When the color scale is included in the tooltip, it shows the hovered value on the scale:

Legend options

Legend options control how the color scale legend is displayed on the visualization. For more information about the legend, refer to Configure a legend.

Annotation options

{{< docs/shared lookup="visualizations/annotations/options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Exemplars

Set the color used to show exemplar data.

Data links and actions

{{< docs/shared lookup="visualizations/datalink-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Field overrides

{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}