Heatmap Panel Type - Visualize Metric Distributions

Heatmap

A Heatmap shows how a distribution changes over time. Each column is a time interval, each row is a value bucket, and the color of a cell shows how many observations fell in that bucket during that interval. A latency heatmap shows the full spread of request durations, which a few percentile lines hide.

When to use a heatmap

• You have a histogram metric, such as a request duration, and you want to see the whole distribution over time.
• You want to find shifts, bimodal patterns, or outliers that an average or a percentile line hides.

For a single aggregated value or a few series over time, use the Time Series panel.

Data Formats

Supported signals

• Metrics

Heatmap panels do not accept logs or traces. The panel draws one query, and the metric type sets where the buckets come from:

• Histogram and exponential histogram metrics carry their own buckets. The panel uses them as rows.
• Gauge and sum metrics have no buckets. The panel puts the values into buckets for you. Use Bucket by to change the spacing of the buckets.

Create a heatmap panel

1. In your dashboard, click New Panel. In the New panel drawer, select Heatmap under Distributions, then click the add button.
2. In the query builder, select a metric. For a histogram metric, keep the Count aggregation.
3. Click Run Query. The panel shows one column per time interval and a color bar labeled COUNT under the chart.
4. Click Save changes.

When you switch an existing panel to Heatmap, the panel keeps only the first query and removes all formulas. A percentile aggregation changes to Count. If you switch back to the earlier panel type, the earlier query returns.

Bucket by

The Bucket by add-on appears below the query for gauge and sum metrics. It does not appear for histogram metrics. If you do not set it, the query uses the finest log axis.

• Log: The bounds are evenly spaced on a log axis, so every band has the same height on screen. Scale goes from -4 (fewest, coarsest bands) to 4 (finest, the default). A scale of 0 gives one band for each doubling of the value.
• Linear: The bounds are evenly spaced from 0 to Max value, which is required. Buckets sets the number of bands, from the default 60 up to 512. All values above Max value go into one overflow band.

The Bounds strip under the controls shows the first bucket edges before you run the query. When a formula is the drawn query, the formula has its own Bucket by controls.

Chart appearance

The Chart appearance section sets how counts map to colors. The Preview at the top shows the result, for example lava · log · 64 steps.

• Color mode: Palette maps each count to a color on a multi-color ramp. Opacity uses one Base color and makes cells with higher counts more opaque. For the base color, pick Group color to give each group its own color, a preset color, or a custom color.
• Palette: ice, moss, rust, graphite, ember, lagoon, orchid, verdant, lava (default), or beacon.
• Color scale: Log (default), Square root, or Linear. Log keeps low counts visible when a few cells have very high counts.
• Color steps: 2 to 128 bands of color. The default is 64.
• Count range: Set Min and Max to fix the counts at the two ends of the ramp. Leave them empty to read the range from the data. Fixed values keep colors the same across time ranges. If Min is greater than Max, an error appears under the fields.

Formatting, axes, and legend

• Formatting & Units: Unit and Decimal places apply to the bucket bounds on the Y-axis. Counts have no unit.
• Axes: Y-axis scale is Auto (default), Linear, Log, or Symlog (symmetric log). Auto uses Log when all bucket bounds are positive and Symlog when the bounds cross zero.
• Legend: Position places the legend Below chart or Right of chart.

Tooltip

When you hover over a cell, the tooltip shows the time interval of the column, the bucket range, and the count. The time interval starts with the date.

• For a query with one group, the tooltip also lists the nearby buckets above and below the hovered one.
• For a query with more than one visible group, the tooltip shows a Group and Contribution table instead. A share below one percent shows as <1%.

To keep the tooltip open, hover over a cell and press P. A Pinned badge appears in its header. Press P or Esc to release it.

Limitations

• Heatmap panels support metrics only.
• You cannot create an alert from a Heatmap panel.
• Heatmap panels do not support drill-down.
• You can download a Heatmap panel as PNG or SVG, but not as CSV.
• The query builder hides Functions and Having for Heatmap panels.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.