# Top List

The **Top List** panel ranks metric values and displays them in list format. Use it to identify the highest or lowest values for a specific metric across labels such as hosts, namespaces, or services.

## Add a Top List Panel

1. Open the dashboard where you want the panel.
2. Click **Add Panel**.

3. In **Choose Visualization**, select **Top List**.

4. In **Graph your data**, click **Select a metric** to start building your query.
5. Enter a descriptive **Title**.
6. Click **Save** to add the panel.

## Build queries (Graph your data)

The query builder defines which metrics are ranked and how they are displayed.

1. Click **Add Query** to create a query. Repeat to add more.
2. Click **Select a metric** to choose the metric name.
3. Use **From** to pick the metric source or namespace.
4. Click **Add Label** to group results by label values (for example, `host`, `pod`, `region`).
5. Select an **Aggregation** (for example, `sum`, `avg`, `max`, `min`) to combine values per label.
6. Use the **Select** dropdown (if available) to set the aggregation interval.
7. Click **Add Functions** to apply transformations (for example, scaling or unit conversion).

|     |     |
| --- | --- |
|  | If multiple queries are added, you can sort and display results from each independently or combine them using formulas. |

## Configure ranking

- **Sort order** — Choose ascending (lowest first) or descending (highest first).
- **Limit** — Set the number of results to display (for example, Top 5, Top 10).
- **Display units** — Apply unit formatting to values (for example, bytes, ms, percentage).

## Apply functions

Functions let you modify the values before ranking.

Examples:
\* **scale()** — Multiply all values by a constant.
\* **round()** — Reduce decimal precision.
\* **moving_avg()** — Smooth values before sorting.

|     |     |
| --- | --- |
|  | Applying expensive transformations to large datasets can impact performance.<br>Test with shorter time ranges when building complex panels. |

## Add formulas

Formulas can calculate new values before ranking.

Example — double the values:

```
2*a
```

Example — compute percentage change between two queries:

```
((a - b) / b) * 100
```

|     |     |
| --- | --- |
|  | Use short aliases (`a`, `b`) or meaningful names in the query list for clearer formulas. |

## Customize appearance

In the **Settings** tab, you can:

- Choose list alignment (horizontal or vertical).
- Show or hide value bars next to labels.
- Set thresholds to color results based on value.
- Adjust font size and spacing.

## Best practices

- Always label metrics meaningfully in the legend.
- Limit the number of displayed results to improve readability.
- Apply sorting and thresholds to highlight critical items.
- Use consistent units for easier comparison across dashboards.