> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Visualize data density and histograms with heat maps

<Note>
  [Classic dashboards](/observe/dashboards/classic-dashboards) have their own panels
  and methods of configuring them. For details about panels in classic dashboards,
  see [Classic dashboard panels](/observe/dashboards/classic-dashboards/classic-panels).
</Note>

A *heat map* visualizes the density of data points across values returned by a
[query](/investigate/querying). 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 or to create a
heat map, see [Panels](/observe/dashboards/panels).

## Heat map queries

Heat maps use one or more metrics
[queries](/observe/dashboards/panels#change-a-panels-query) to retrieve data for
visualization. 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.

- **Truncation strategy**: Truncation strategy to apply to the query. This modifies
  the raw query. Observability Platform selects the best strategy for fit when
  possible, and displays `Auto` as the selected strategy.

  Available strategies are:

  * `Auto`
  * `Off`
  * `Avg`
  * `Min`
  * `Max`

  Changing your truncation strategy adds truncation information as additional bands
  or bars on your chart and details into the legend.

### Query examples

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

* [Exponential histograms](/control/shaping/shape-metrics/types#cumulative-exponential-histograms):

  ```shell theme={null}
  sum(rate(duration_milliseconds{app_name="$app_name"}[5m]))
  ```

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

* Explicit histograms:

  ```shell theme={null}
  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:

  ```shell theme={null}
  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 <Icon icon="settings" /> **Settings**](/observe/dashboards/panels#edit-a-panel).

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](/tooling/chronoctl)
and [Terraform](/tooling/infrastructure/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. 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](/overview/concepts/time-units)
    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**, Observability 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.