Visualize data density and histograms with heat maps

A heat map visualizes the density of data points across values returned by a query. Heat maps depict several ranges of values, referred to as buckets, as colored segments for each time recorded in data points. The color of each bucket corresponds to the number of data points whose values are inside of that bucket’s range. Colors typically fall in a gradient where the number of data points in a bucket correspond to that bucket color’s intensity in the heat map.

Heat maps are especially well suited to visualize histograms, which collect data points into buckets of values. Chronosphere Observability Platform supports visualizing Prometheus histograms and exponential histograms as heat maps.

For details about the configuration options common to all panels, see Panels.

To create a heat map or learn more about the configuration options common to all panels, see Panels.

Heat map queries

Bar charts use one or more metrics queries to retrieve data to visualize. Heat maps use only Prometheus metrics.

Heat maps use the following query Options to refine the displayed information.

• Min step: The step parameter of the PromQL query.

• Downsampling strategy: Select a downsampling strategy to apply to and modify the raw query.

• Truncation strategy: Truncation strategy to apply to the query. This modifies the raw query.

Query examples

The following queries are examples of how you might use different metrics to visualize data on a heatmap:

• Exponential histograms:

  sum(rate(duration_milliseconds{app_name="$app_name"}[5m]))

  Using this query generates a heatmap where you can see a rate of application duration time, grouped by bucket.

• Explicit histograms:

  sum by (le)(rate(duration_milliseconds_bucket{app_name="$app_name"}[5m]))

  This query generates a map similar to the previous, but uses classic histograms.

• Non-histogram:

  sum by (pod)(rate(container_cpu_usage_seconds_total{container=~"chronocollector"}[5m]))

  This query generates a heatmap showing CPU utilization for pods, with buckets generated by the panel based on the distribution of the returned series. The graph renders a count of how many pods have utilization grouped into a given bucket on the graph. Time series panels render series for individual pods. The heatmap helps identify what typical utilization looks like and how much variance there is across pods.

Use a heat map’s tooltip

When you hold the pointer over a bucket in a heat map, Observability Platform displays a tooltip that displays the bucket’s value range and count of matching data points.

Configure a heat map

You can configure a heat map by modifying its Settings.

Any changes you make in the panel’s Settings tab are immediately reflected in the Preview pane, but take effect only when you click Apply in the Edit panel interface and then Save the dashboard.

Observability Platform doesn’t fully support directly editing a panel’s JSON representation and recommends configuring panels in the user interface. Use the JSON representation only for managing your configuration as code with tools such as Chronoctl and Terraform.

To discard and revert all of the panel’s settings to their defaults, click Reset all settings to defaults.

Modify a heat map’s legend

The Legend section in a heat map’s Settings tab controls whether to display a legend alongside the heat map, and how the heat map’s color gradient corresponds to data point counts for a bucket.

• Show: Toggles whether to display the legend. Defaults to enabled.

• Position: Selects whether to display the legend Bottom or to the Right of the heat map. Defaults to Right.

  Units, abbreviations, and decimal places configured in the Y axis settings also apply here.

Modify a heat map’s visual representation

The Visual section in a heat map’s Settings tab controls how Observability Platform visualizes data in the heat map, including its color palette and displayed value range.

• Color palette: Determines the heat map gradient’s color palette. For example, you can select Defaults to Orange->Red.
• Invert palette: Toggles whether to invert the mapping of the color palette to data point counts. Defaults to false.
• Min value: Optionally defines the minimum data point count to map to the lowest value in the color palette. Values smaller than the Min Value are still displayed using the color palette’s lowest value. Defaults to the smallest value returned by the query.
• Max value: Optionally defines the maximum data point count to map to the highest value in the color palette. Values larger than the Max Value are still displayed using the color palette’s highest value. Defaults to the largest value returned by the query.
• Hide zeros: Toggles whether to hide buckets that counted zero results matching their corresponding values from the heatmap. Defaults to true.

Modify a heat map’s Y axis

The Y axis section in a heat map’s Settings tab controls whether Observability Platform renders a heat map’s Y axis, and if so what information it includes.

These settings apply to all values on the heat map, including any values you enabled in its legend.

• Unit: Defines the unit used to render the Y axis. This has the most significant effect when you enable Abbreviate. Defaults to Decimal.

  • Decimal: Base 10 values. Observability Platform renders a value of 1000000 as 1M.
  • Bytes: As decimal multiple-byte units. Observability Platform renders a value of 1000000 as 1MB.
  • Time: Determines the unit of time that Observability Platform uses to interpret a numeric value.
  • Percent: Interprets the value as a percentile, representing 0% to 100% on a range of either 0.0 to 1.0 (Percent (0.0-1.0)) or 0 and 100 (Percent (0-100)).

  For example, Observability Platform renders a value of 1.0 in Percent (0.0-1.0) as 100%, and in Percent (0-100) as 1%.

• Decimals: Defines how many decimal places Observability Platform renders for values. Default renders decimal places only if necessary and rounds to the nearest value. Numeric values from 0 to 4 render the corresponding number of decimal places.

• Abbreviate: Toggles whether to abbreviate units on the Y axis. For example, if you enable Abbreviate, Observation Platform renders a value of 100000000 as 100M. You can toggle this setting only if you set the Unit to Decimal or Bytes; Time units are always abbreviated and Percent values don’t require it. Defaults to true.

• Label: Renders the given text vertically next to the Y axis. Defaults to no value.