# Heatmap widget

Use a heatmap to visualize data intensity across two dimensions and quickly identify high-activity areas or trends.

## Overview

A heatmap displays the intensity of data values using color. Each cell represents the aggregated value of data at the intersection of 2 dimensions—such as **time × service**, **endpoint × latency**, or **region × status code**. This makes it easy to identify spikes, clusters, and patterns that might be hard to see in a line or bar chart.

Use heatmaps when you need to:

- Visualize distribution or density across two dimensions.
- Quickly catch hotspots, trends, and anomalies over time or by category.
- Drill from events directly into logs, traces, or metrics for deeper analysis.

## Create a heatmap

1. In your dashboard, select **Add Widget**.

1. Drag and drop the **Heatmap widget** into your dashboard.

1. In the [**Query Builder**](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/query-builder/index.md), use the **Function** panel to group and aggregate your data for the heatmap.

   - In **Group by**, select **up to 5** categories or fields you want to appear on the X and Y axes. (for example, `subsystem`, `severity`, `region`).
   - Select an aggregation function such as **Count**, **Sum**, or **Average** to calculate the value represented by color intensity.

   Note

   - Fields used in **Group by** for heatmap axes must be **string**, **timestamp**, or **severity**.
   - If a field is numeric (such as `status_code`), [cast it to a string](https://coralogix.com/docs/dataprime/user-guide/dpxl/#data-types) in a DataPrime query before grouping (for example: `status_code:string`).
   - To control which field appears on the X-axis and which on the Y-axis, open the **Settings** panel and select **Switch Axis**, or drag and assign parameters directly to each axis.

1. (Optional) Add filters or time range adjustments.

1. Select **Save changes** to add the widget to your dashboard.

## Define widget parameters

Configure your heatmap’s appearance and data display options in the widget’s **Settings** panel. Use these parameters to control the display, color, and labeling of values across the visualization.

### Visual management

In the **Settings** panel, expand **GENERAL SETTINGS** to adjust the heatmap axis data, color display and density in **VISUAL MANAGEMENT**.

- **Swap axes:** Switch the X and Y axes for a different layout of the same data.

- **Show cell values:** Toggle to overlay numeric values inside each cell. Useful where cells are larger and readable.

- **Color palette:** Select a predefined color palette to represent data intensity. You can reverse the color order (light → dark or dark → light).

- **Legend scale:** Select the color scheme using the legend configuration. It maps values from light → dark by default. Use **Min** and **Max** thresholds to control the color scale range and improve readability for data with wide or uneven distributions.

- **Scale type:** Choose between:

  - **Linear** (default): Colors change evenly across values.
  - **Logarithmic**: Applies globally to the Z-access (color-intensity bar) for datasets with wide value ranges.

- **Date format:** When a timestamp field appears on the X-axis, select how time labels are displayed. The default is **Auto (adaptive)**, which adjusts the format based on the selected time range. Available formats:

  | Format          | Example               |
  | --------------- | --------------------- |
  | Auto (adaptive) | Adjusts automatically |
  | DD/MM           | 25/04                 |
  | MM/DD           | 04/25                 |
  | HH:mm           | 14:30                 |
  | DD/MM HH:mm     | 25/04 14:30           |
  | HH:mm DD/MM     | 14:30 25/04           |
  | MM/DD HH:mm     | 04/25 14:30           |
  | HH:mm MM/DD     | 14:30 04/25           |

### Tooltip management

Customize what information appears when you hover over a Heatmap cell. By default, the tooltip shows a simple value such as `value = 3`.

- **Text message:** Define the message or value displayed when hovering over a cell. This can include the X- and Y-axis attributes and the aggregated value (Z-axis).

  Note

  To show cell values in your hover tooltip, use `{{ }}` syntax in the **Text message** field.

  As you type, a dropdown lists available dynamic fields such as the aggregation result or axis labels.

  Use `{{count_0}}` to display the cell's count value in the tooltip.

- **Labels:** Select which labels or attributes to include in the tooltip (for example, **service**, **category**, or **application**).

Use this field to control how detailed the hover tooltip appears, especially in dense Heatmaps.

### Units management

- **Units:** Define a display unit for the aggregated value, such as **ms**, **%**, or **count**.
- **Decimals:** Select the maximum number of decimal places to display.
- **Precision**: Toggle to show full unrounded values instead of rounded ones.
- **Min–max limits**: Define minimum and maximum values for the color scale.

### Custom actions

Use [Custom Actions](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/create-and-manage-custom-actions/index.md) to trigger workflows directly from any cell in your heatmap. Create actions with custom links to carry the cell’s context—such as field values, filters, and time range—so you can open other dashboards or trigger external systems with that same context.

To add a custom action, select in the **CUSTOM ACTIONS** section of the **Settings** panel, then name and enter a target URL.

After you create the action, selecting a cell in the heatmap opens a quick actions menu that includes your custom action.

## Use quick actions

Select a cell to open the context menu:

- **Open Explore**: Opens the logs or traces **Explore** view with filters from the selected cell.
- **Filter in**: Add the cell’s data and time filters to the dashboard query.
- **Filter out**: Exclude the cell’s data from the dashboard query.
- **Copy name**: Copy the cell label or key=value pair.

Note

Filters apply at the dashboard level, allowing other widgets to update automatically.

## Performance and best practices

- Keep under 2,000 data rows (total number of X×Y combinations returned by the query) for responsive visualization. If your query returns more, increase the time range or reduce the number of **Group By** fields.
- Use no more than **5 grouping fields** per widget; additional fields might affect readability and performance.
- Avoid grouping by high-cardinality labels like `user_id`.
- Limit grouping fields to avoid overcrowded visualization results.

## Example use cases

**Errors over time by service**

- Visualize error spikes over time.
- **X-axis**: Timestamp
- **Y-axis**: System or service
- **Filter**: Limit data to error events
- **Value**: Count of errors (drives color intensity)

Use to determine where and when errors occur across your system.

**Status codes by region**

- Compare response patterns across regions to detect latency errors.
- **X-axis**: Region
- **Y-axis**: Status code
- **Value**: HTTP-request count (drives color intensity)

Note

If `status_code` is numeric in your logs, cast it to a string in a DataPrime query (for example, `status_code:string`) before using it on a heatmap axis.

Shows whether certain regions experience more failures or unusual status patterns.

## Related resources

- [Custom actions](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/create-and-manage-custom-actions/index.md) — Add drilldowns from cells to other features or open external workspaces.
- [Legend configuration for widgets](https://coralogix.com/docs/user-guides/custom-dashboards/widgets/legend-configuration-for-widgets/index.md) — Manage color legends and palettes.
- [Annotations](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/create-annotations/index.md) — Overlay deployments or recurring events on time-based charts.

## Next steps

Learn how to use the [markdown widget](https://coralogix.com/docs/user-guides/custom-dashboards/widgets/markdown-widget/index.md) to add contextual notes and documentation to your dashboards.