# Metrics Explorer

> Use Last9's native metrics UI to build PromQL queries, visualize results, and promote them to a dashboard or alert without rebuilding the query elsewhere.

Source: https://last9.io/docs/metrics-explorer/

Metrics Explorer is Last9's native UI for querying metrics. Build queries visually with the Builder mode, drop into a PromQL editor for advanced cases, and promote any query you have running into a [dashboard](/docs/dashboards/) panel or an alert without rewriting it.

Open it at [app.last9.io/metrics](https://app.last9.io/metrics). With no filters applied, Metrics Explorer surfaces a discovery grid of recent metrics in your cluster so you can pick one to drill into.

![Metrics Explorer default view with the discovery grid](../../../../assets/content/docs/metrics/metrics-explorer-default.png)

## Query Modes

Metrics Explorer has two query modes. Switch between them at any time using the toggle at the top of the query bar — your work carries over.

| Mode        | When to use                                                                              |
| ----------- | ---------------------------------------------------------------------------------------- |
| **Builder** | Pick a metric, add label filters, layer range and aggregation stages with no PromQL      |
| **PromQL**  | Write or paste raw PromQL with autocomplete; useful for advanced functions and debugging |

:::tip
Switching from Builder to PromQL converts your current builder query into PromQL. Switching back drops any hand-written PromQL that wasn't built from the visual stages.
:::

### Builder Mode

Builder mode constructs PromQL from a small set of stages. Stages compose left-to-right into the final query.

| Stage                  | Purpose                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Filter**             | Pick a metric and add label matchers (`=`, `!=`, `=~`, `!~`)                                                              |
| **Range**              | Wrap the series with a range function (`rate`, `irate`, `increase`, `*_over_time`, ...)                                   |
| **Aggregate**          | Apply an aggregation (`sum`, `avg`, `min`, `max`, `count`, `topk`, `quantile`, ...) with optional `by`/`without` grouping |
| **Histogram Quantile** | Compute a quantile from a classic histogram (added as the outermost stage)                                                |

Stages follow PromQL composition rules: at most one Range stage (innermost), any number of Aggregate stages, and at most one Histogram Quantile stage (outermost). Builder mode picks sensible defaults based on the selected metric type — for example, counters get `rate` + `sum by ()`, gauges get `avg by ()`, and classic histograms get `rate` + `sum by (le)`.

:::tip
Builder mode only exposes the most common operators and functions. For anything else — binary operators, vector matching, math between two metrics, `absent()`, `clamp_*`, `label_replace`, multi-metric queries, and so on — switch to **PromQL** mode for full PromQL compatibility.
:::

1. Navigate to [Metrics Explorer](https://app.last9.io/metrics)
2. In the **Filter** stage, pick a metric and optionally add label matchers
3. Adjust or add a **Range** stage. Pick a function and a window — `$__rate_interval` adapts automatically to the dashboard time range
4. Adjust or add an **Aggregate** stage. Choose a function and (optionally) a `by` or `without` grouping
5. For classic histograms, add a **Histogram Quantile** stage to compute the desired percentile (default `0.99`)
6. Click **Run Query** or press `⌘`+`⏎` (macOS) / `Ctrl`+`⏎` to execute

![Metrics Explorer with a Filter, Range, and Aggregate stage and the resulting visualization](../../../../assets/content/docs/metrics/metrics-explorer-with-query.png)

The PromQL preview under the stages shows exactly what will be sent on **Run Query**. Use **Add to Dashboard** or **Create Alert** in the results panel to promote the query without rewriting it.

### PromQL Mode

PromQL mode is an editor backed by autocomplete against your live metrics catalog. Use it when you need anything beyond what Builder mode exposes — binary operators, vector matching, math across two metrics, `absent()`, `clamp_*`, `label_replace`, multi-metric queries, and so on.

- LogQL-style autocomplete is supported for metric names, labels, and label values
- Queries are not auto-run. Click **Run Query** or use `⌘`+`⏎` / `Ctrl`+`⏎`
- Use the [built-in dashboard variables](/docs/using-dashboards/#built-in-variables) like `$__rate_interval` and `$__interval` for portable queries

:::tip
Use `$__rate_interval` instead of hardcoded windows in `rate()`. Queries built this way translate cleanly when promoted to a dashboard panel.
:::

## Range Functions

The Range stage supports the following PromQL range-vector functions:

| Function                                                                              | Notes                                                             |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `rate`, `irate`                                                                       | Per-second average and instantaneous rate of a counter            |
| `increase`                                                                            | Total increase of a counter over the window                       |
| `delta`, `idelta`                                                                     | Difference and instantaneous difference of a gauge                |
| `sum_over_time`, `avg_over_time`, `min_over_time`, `max_over_time`, `count_over_time` | Time-window aggregations                                          |
| `quantile_over_time`                                                                  | Quantile of a series over the window (takes a quantile parameter) |
| `stddev_over_time`, `stdvar_over_time`                                                | Standard deviation and variance over the window                   |
| `last_over_time`, `present_over_time`, `absent_over_time`, `mad_over_time`            | Latest value, presence checks, and median absolute deviation      |

## Aggregation Functions

The Aggregate stage supports:

- **Reducers:** `sum`, `avg`, `min`, `max`, `count`, `count_values`, `group`
- **Spread:** `stddev`, `stdvar`
- **Selectors:** `topk`, `bottomk` (default `k = 10`)
- **Quantile:** `quantile` (default `0.99`)

Each aggregation can be grouped with `by (<labels>)` or `without (<labels>)` to control how series are collapsed.

## Adding a Query to a Dashboard

Once a query is running, you can promote it to a [dashboard](/docs/dashboards/) panel without rewriting it.

1. Run a query in either Builder or PromQL mode
2. In the results panel, click **Add to Dashboard**
3. Pick an existing dashboard or create a new one, and give the panel a descriptive name
4. The visualization type (timeseries or table) is preserved on the dashboard panel

![Add to Dashboard modal with dashboard selector and panel name](../../../../assets/content/docs/metrics/metrics-explorer-add-to-dashboard.png)

The promoted panel uses the exact PromQL from the explorer. If you used a built-in variable like `$__rate_interval`, the panel adapts to the dashboard's time range automatically.

## Creating Alerts from Queries

You can turn any running query into a metric alert without leaving Metrics Explorer.

![Create Alert modal with PromQL preview, threshold, sensitivity, severity, and destinations](../../../../assets/content/docs/metrics/metrics-explorer-create-alert.png)

1. Run the query you want to alert on
2. In the results panel, click **Create Alert**
3. Configure the alert:

   | Field                     | Description                                                                                 |
   | ------------------------- | ------------------------------------------------------------------------------------------- |
   | **Rule Name**             | Unique name for the alert rule                                                              |
   | **Threshold**             | Operator (`>`, `<`, `>=`, `<=`, `==`, `!=`) and value                                       |
   | **Sensitivity**           | Trigger when the threshold is breached for **N bad minutes** out of any **M total minutes** |
   | **Severity**              | `critical`, `warning`, or `info`                                                            |
   | **Notification Grouping** | Group all timeseries into a single notification, or notify per-series                       |
   | **Alert Destinations**    | One or more [notification channels](/docs/notification-channels/) to send the alert to      |
   | **Annotations**           | Optional rule description and runbook URL                                                   |

4. Click **Create Alert**

The PromQL query is sent as-is to [Alerting](/docs/alerting/), where you can later edit thresholds, destinations, and annotations.

## Best Practices

**Query construction:**

- Filter on `service`, `env`, or other low-cardinality labels first to keep queries fast
- Use `$__rate_interval` so queries scale across short and long time ranges
- Add a `by (<label>)` grouping when you want one series per dimension; otherwise series collapse into a single line

**Dashboard promotion:**

- Run the query and confirm the visualization before promoting
- Give panels short, descriptive names — they become the panel title on the dashboard
- For percentile queries, finalize the histogram quantile stage in the explorer before adding the panel

**Alerting:**

- Use sensitivity windows (`N bad minutes out of M`) to avoid flapping on transient spikes
- Set **Notification Grouping** when an alert may fire across many series at once and you want a single notification per evaluation

---

## Troubleshooting

- **Query returns no data**

  - **Verify the metric exists.** Switch to Builder mode and confirm the metric appears in the picker for the selected time range.
  - **Check label matchers.** Regex matchers (`=~`, `!~`) are anchored — use `.*` to match substrings.
  - **Widen the time range.** Newly ingested metrics may not yet be queryable in the last few seconds.

- **"Time range too large" or "too many samples"**

  - Reduce the time range, narrow filters, or aggregate aggressively (`sum`, `avg by (...)`) before plotting.

- **Builder defaults look wrong for a metric**

  - The default range/aggregate stages are picked from the metric type. For unusual metrics, switch to PromQL mode and write the query directly.

- **Add to Dashboard or Create Alert is missing**

  - Both actions live in the results panel and only appear after a query has run successfully. Press **Run Query** first.

Please get in touch with us on [Discord](https://discord.com/invite/Q3p2EEucx9) or [Email](mailto:support@last9.io) if you have any questions.