Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fcustom-dashboards%2Fwidgets%2Fstat-widget.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fcustom-dashboards%2Fwidgets%2Fstat-widget.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# Stat widget

Display a single numeric or string value as a compact, standalone indicator on a [Custom Dashboard](https://docs-docusaurus.kinsta.page/user-guides/custom-dashboards/introduction/.md). Use the Stat widget to surface the most important value from a query, a selected field, or a dashboard variable—without requiring a chart or gauge.

Each Stat widget presents a primary value and can optionally include a title and a label derived from value mappings. Color formatting applied to the value text or the widget background makes it easy to spot issues at a glance.

When a query returns multiple results, the widget displays each result as an independent stat element arranged in a row, with pagination controls to navigate large result sets.

[![Stat widget in multi-value mode showing log counts per service as individual stat elements in a row, with a legend on the right listing service names](/assets/images/stat-widget-multi-value-b196754c651e5776ba72bf83bbdcdc50.webp)](https://docs-docusaurus.kinsta.page/assets/images/stat-widget-multi-value-b196754c651e5776ba72bf83bbdcdc50.webp)

## What you need[​](#what-you-need "Direct link to What you need")

* Access to Custom Dashboards in Coralogix.
* A query that returns at least one numeric or string value.

## Set up[​](#set-up "Direct link to Set up")

To add a Stat widget to a Custom Dashboard:

1. In **Custom Dashboards**, select **Add widget**.
2. Drag and drop the **Stat widget** from the sidebar into your dashboard.

## Use the Query Builder to create a query[​](#use-the-query-builder-to-create-a-query "Direct link to Use the Query Builder to create a query")

In the bottom panel, build your query using the [Query Builder](https://docs-docusaurus.kinsta.page/user-guides/custom-dashboards/tutorials/query-builder/.md).

## Define the widget parameters[​](#define-the-widget-parameters "Direct link to Define the widget parameters")

Configure the widget in the settings panel.

### General settings[​](#general-settings "Direct link to General settings")

**Custom actions**. Add [custom actions](https://docs-docusaurus.kinsta.page/user-guides/custom-dashboards/tutorials/create-and-manage-custom-actions/.md) to link to external resources or trigger workflows. Select **+ New action** to configure.

### Query parameters[​](#query-parameters "Direct link to Query parameters")

**Group by**. Group query results by one or more label or field values. Each unique group is displayed as a separate stat element.

**Units management**. Control how values are displayed.

* **Precision**. Toggle on to display the raw, unrounded value returned by the query. When toggled off, the value is shortened and rounded based on the **Decimal** setting.

* **Units**. Select a unit type, such as `ms`, `%`, or `bytes`, or leave as **None**. Select **Datetime ISO** to convert a Unix timestamp or string value into a human-readable ISO 8601 date-time string. See [Datetime ISO unit](#datetime-iso-unit) for supported input formats. Custom units are saved with the widget and are not added to the global unit list.

* **Decimal**. Set the number of decimal places to display, from 0 to 15.

### Mapping and thresholds[​](#mapping-and-thresholds "Direct link to Mapping and thresholds")

Use mapping and thresholds to convert raw values into labels and to trigger visual formatting based on value ranges.

**Auto min max from data**. When enabled, the widget automatically detects the minimum and maximum values from your query results and uses them as the threshold baseline. Disable to set **Min** and **Max** manually.

**Threshold type**. Select how threshold values are interpreted:

* **Relative**: Thresholds are evaluated as percentages of the min-max range.
* **Absolute**: Thresholds are evaluated as exact numeric values.

**Thresholds**. Define color levels that trigger based on the query value:

1. Select **+ Add Threshold**.
2. Enter the value or percentage that activates the threshold.
3. Optionally, enter a label for this level (for example, `Good`, `Warning`, or `Critical`).
4. Select a color to represent this level.

**Mapping type**. Translate raw values into human-readable labels or apply color overrides based on a specific pattern. Select the mapping type that matches your data:

* **Range**: Matches numeric values within a defined range. Useful for continuous metrics such as CPU usage or latency.

  | Range  | Label    | Color  |
  | ------ | -------- | ------ |
  | 0-30   | Healthy  | Green  |
  | 30-70  | Warning  | Yellow |
  | 70-100 | Critical | Red    |

* **Value**: Matches a specific exact value. Useful for categorical data such as severity levels or status codes.

  | Value   | Label    | Color  |
  | ------- | -------- | ------ |
  | `ERROR` | Critical | Red    |
  | `WARN`  | Warning  | Yellow |
  | `INFO`  | Healthy  | Green  |

* **Regex**: Matches values using a regular expression. Useful when values follow a structured naming convention.

  | Pattern     | Label   | Color  |
  | ----------- | ------- | ------ |
  | `.*error.*` | Error   | Red    |
  | `.*warn.*`  | Warning | Yellow |

For each mapping rule, assign a label and a color. The label appears as the label element in the widget when a match is found.

### Color options[​](#color-options "Direct link to Color options")

Select how the mapped color is applied to the widget:

* **Value**: Applies the color to the primary value text. Use this when multiple Stat widgets appear together and you want a subtle visual indicator.
* **Background**: Fills the entire widget background with the color. Use this when the widget functions as a status tile and you want the color to be immediately visible.
* **Row**: Applies the color to the entire row of stat elements. Use this when displaying grouped results and you want to highlight the row rather than individual values.

### Stat visual management[​](#stat-visual-management "Direct link to Stat visual management")

Control what the widget displays and where each value comes from.

**Primary value**. Select the query field or aggregation result to display as the main value. Optionally, enter a **Display name** to override the field name shown in the widget.

Examples of primary value sources:

* `{{count_0}}`: the count returned by the first `count()` aggregation in the query (zero-based index)
* `{{$m.severity}}`: the `severity` metadata field from the query result
* `${pod.name}`: the value of the `pod.name` dashboard variable

**Title**. Toggle on to display a title above the primary value. Select the source:

* **Field or aggregation**: Select a query field or aggregation result, and optionally enter a **Display name** to override the label.
* **Mapped value**: Uses the label from the mapping rule that matched the primary value. If no rule matches, the raw primary value is shown. To always show a mapped label, add a `.*` regex rule as a catch-all fallback.

Titles are useful for providing context, such as severity level, service name, or environment name.

**Label**. Toggle on to display a label below the primary value. Select the source:

* **Field or aggregation**: Select a query field or aggregation result, and optionally enter a **Display name**.
* **Mapped value**: Uses the label from the mapping rule that matched the primary value. If no rule matches, the raw primary value is shown. To always show a mapped label, add a `.*` regex rule as a catch-all fallback.

Note

**Mapped value** is available for Title and Label, but not for Primary value. Primary value is the source input for all mapping calculations; selecting a mapped result as the primary value would create a circular reference.

## Multi-value display[​](#multi-value-display "Direct link to Multi-value display")

Note

The Stat widget currently supports a single query per widget. Multi-query configurations will be supported at a later time.

When your query returns multiple rows—for example, 1 result per pod or 1 result per service—the Stat widget displays each result as a separate stat element arranged in a row, with pagination to navigate across all results.

In this mode:

* Each stat element displays its own primary value.
* Title and label appear per element if configured.
* Color formatting is not applied to maintain visual consistency across elements.

To control how many stat elements appear per row, resize the widget horizontally.

Selecting a stat element opens a context menu with the following options:

* **Filter out**: Excludes the selected value from the dashboard filter.
* **Filter in**: Restricts the dashboard to show only the selected value.
* **Open Explore**: Opens the value in Explore for deeper investigation.
* **Copy name**: Copies the element name to the clipboard.

[![Stat widget context menu open on a stat element, showing Filter out, Filter in, Open Explore, and Copy name options](/assets/images/stat-widget-context-menu-cc344e73c51faec9cd996279868501e0.webp)](https://docs-docusaurus.kinsta.page/assets/images/stat-widget-context-menu-cc344e73c51faec9cd996279868501e0.webp)

## Datetime ISO unit[​](#datetime-iso-unit "Direct link to Datetime ISO unit")

The **Datetime ISO** unit converts a raw value into a human-readable ISO 8601 date-time string (for example, `2026-03-18T08:51:08.000Z`). Select it from the **Units** dropdown under the **DATETIME** category.

The Datetime ISO unit accepts the following input formats:

| Form                       | Example                  | Notes                              |
| -------------------------- | ------------------------ | ---------------------------------- |
| Milliseconds               | `1710720000000`          | Since Unix epoch (Jan 1, 1970 UTC) |
| ISO 8601 string            | `"2024-03-18T12:00:00Z"` | Preferred string format            |
| RFC 2822 / informal string | `"Mar 18, 2024"`         | Implementation-dependent; avoid    |

Coralogix recommends using Unix epoch milliseconds or ISO 8601 strings as inputs. RFC 2822 and informal date strings are implementation-dependent and might produce inconsistent results.

## Example use case[​](#example-use-case "Direct link to Example use case")

The following example creates a Stat widget that monitors critical log volume in real time.

### Step 1: build the query[​](#step-1-build-the-query "Direct link to Step 1: build the query")

Add a Stat widget to your dashboard and build a query in the [Query Builder](https://docs-docusaurus.kinsta.page/user-guides/custom-dashboards/tutorials/query-builder/.md) to count critical severity logs:

```
source logs

| filter $m.severity == CRITICAL

| stats count()
```

The query returns a single count value: the number of critical log events in the selected time range.

### Step 2: configure the parameters[​](#step-2-configure-the-parameters "Direct link to Step 2: configure the parameters")

In the settings panel:

* Leave **Group by** empty, or add a field label to see counts per application.
* In **Units management**, set **Units** to **None** and **Decimal** to `0`.

### Step 3: add a value mapping[​](#step-3-add-a-value-mapping "Direct link to Step 3: add a value mapping")

In the **Mapping** tab, select **Range** and define the following rules:

| Range | Label    | Color  |
| ----- | -------- | ------ |
| 0-0   | Healthy  | Green  |
| 1-100 | Elevated | Yellow |
| 101+  | Critical | Red    |

### Step 4: set the color mode[​](#step-4-set-the-color-mode "Direct link to Step 4: set the color mode")

Under **Color options**, select **Background** so the widget background changes color based on the threshold.

### Step 5: configure the display[​](#step-5-configure-the-display "Direct link to Step 5: configure the display")

Under **Stat visual management**:

* Set **Primary value** to `{{count_0}}`.
* Toggle on **Title** and set it to `{{$m.severity}}` to show the severity level.
* Toggle on **Label** to display the mapped label (for example, `Healthy`, `Elevated`, or `Critical`).

The widget now displays the current count of critical logs with a color-coded background that immediately signals system health.

## Permissions[​](#permissions "Direct link to Permissions")

| Resource          | Action | Description                              |
| ----------------- | ------ | ---------------------------------------- |
| Custom Dashboards | View   | View dashboards containing Stat widgets. |
| Custom Dashboards | Edit   | Add, configure, and remove Stat widgets. |

## Learn more[​](#learn-more "Direct link to Learn more")

* [Custom Dashboards](https://docs-docusaurus.kinsta.page/user-guides/custom-dashboards/introduction/.md)
* [Query Builder](https://docs-docusaurus.kinsta.page/user-guides/custom-dashboards/tutorials/query-builder/.md)
* [Create and manage custom actions](https://docs-docusaurus.kinsta.page/user-guides/custom-dashboards/tutorials/create-and-manage-custom-actions/.md)
* [Legend configuration for widgets](https://docs-docusaurus.kinsta.page/user-guides/custom-dashboards/widgets/legend-configuration-for-widgets/.md)

## Next steps[​](#next-steps "Direct link to Next steps")

Learn how to [configure legends for your widgets](https://docs-docusaurus.kinsta.page/user-guides/custom-dashboards/widgets/legend-configuration-for-widgets/.md).