# Stat widget

Display a single numeric or string value as a compact, standalone indicator on a [Custom Dashboard](https://coralogix.com/docs/user-guides/custom-dashboards/getting-started/index.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.

## What you need

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

## Set up

To add a Stat widget to a Custom Dashboard:

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

## Use the Query Builder to create a query

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

## Define the widget parameters

Configure the widget in the settings panel.

### General settings

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

### 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

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**.
1. Enter the value or percentage that activates the threshold.
1. Optionally, enter a label for this level (for example, `Good`, `Warning`, or `Critical`).
1. 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

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

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

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.

## 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

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

### Step 1: build the query

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

```text
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

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

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

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

### 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

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

## Learn more

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

## Next steps

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